PaperSpine Open Release Beta 全解析：从交稿完成到受控一键开源的九步发布路线

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用

导读

本文以 PaperSpine5 的 Open Release Beta 参考文档为核心，完整梳理"论文/交付包稳定之后"如何为代码、数据、图表、预印本、实验方案、注册表与学科数据仓库增加受控的发布分支。你将掌握open_release.py的全部 CLI 操作与 JSON 契约、从 Select 到 Record 的九步必选路线、7 种预检状态与结构化权限反馈、医学与人类数据的逐仓库路由边界，以及"哈希绑定 + 用户最终确认 + 精确动作 Ticket"的安全与幂等设计。文中的操作与状态均可在仓库源码 src/scripts/open_release.py 中逐行验证，配套契约 Schema 位于 src/skill/references/contracts/。

一、定位与边界：它是什么，不是什么

Open Release Beta 是一个post-delivery（交稿之后）的发布 playbook，严格遵循三个前置约束：

1. 只在交付包稳定后使用——该 playbook 不是写作/审稿流程的一部分，不应在稿件还在返修时引入；
2. 不替代期刊投稿——它为代码、数据、图表、预印本、协议、注册表和领域仓库增加发布通道，与期刊评审/发表流程相互独立；
3. 永不是BUNDLE_READY的自动延续——交稿完成信号不会自动触发发布，必须显式进入本流程。

关于"一键发布"的承诺，文档给出了明确的正反定义：

• 正面：一次用户选择 + 一次最终确认，即可授权宿主 Agent（host Agent）在当前用户电脑上执行"所有当前具备资格的平台动作"；
• 反面：它不能绕过平台登录、作者资格、机构授权、策展（curation）、审核、费用、许可选择、伦理审批或受控访问规则。

从源码 src/scripts/open_release.py 顶部的模块 docstring 可以看到这一边界的工程化表达：模块"永远不存储凭据、永远不自行执行任何外部发布；宿主 Agent 只能依据已授权的 release ticket 行动"。这意味着整个模块是一个本地准备与审计器，外部动作的执行权被刻意隔离。

二、接口与操作总览

2.1 三条核心 CLI 命令

参考文档给出了三个入口命令：

python scripts/open_release.py describe python scripts/open_release.py catalog --domain medicine --artifact-role clinical_signals python scripts/open_release.py invoke <open-release-invocation.json>

对应源码中build_parser()（src/scripts/open_release.py）定义的子命令：describe输出稳定的接口描述；catalog按 domain、artifact-role、sensitivity 给出平台推荐；invoke读取一份 invocation JSON 并按其中operation字段路由到具体操作。此外还支持preflight <plan>、prepare <plan> <output_dir>、authorize <manifest> <confirmation> <output_dir>、record <ticket> <receipts> <output_dir>四个直接子命令。

源码调用方可直接导入public_interface_descriptor()与invoke_open_release(request_path)；安装版 Skill 的调用方使用scripts/open_release.py，源码调用方使用src/scripts/open_release.py。

2.2 操作与状态映射

open-release-interface.md 给出了五个操作的状态迁移矩阵，这是理解整个流程的骨架：

关键约束：只有authorize能返回signals.external_action_authorized=true，且必须先完成产物漂移检查与哈希绑定的最终用户确认；模块本身仍不执行网络发布，宿主执行器消费 ticket 后行动。

2.3 Invocation 请求示例

{ "contract": "paperspine.open-release.invoke-request", "interface_version": "0.1-beta", "operation": "preflight", "project_root": ".", "inputs": { "plan": "paper_rewriting_output/open_release/open_release_plan.json" }, "options": {} }

所有输入/输出路径必须位于 invocation 的project_root之内；prepare/authorize/record的输出目录必须为新建或空目录（源码ensure_new_output()会直接拒绝非空目录）。operation的合法取值由 open-release-invocation.schema.json 枚举为catalog、preflight、prepare、authorize、record，且每个操作对inputs/outputs的必填字段由 Schema 中的条件约束（allOf+if/then）精确限定。

三、九步必选路线（Required route）

参考文档定义了从选择平台到记录回执的九个强制步骤，下面结合源码逐一步骤展开其内部机制。

步骤 1：Select（选择）

只根据论文推断domain（学科域）与 artifact 类型（产物角色），向用户展示平台推荐与边界，然后让用户自行勾选平台。文档特别强调：推荐不等于同意发布（A recommendation is not consent to publish）。

源码中recommendation_catalog()（src/scripts/open_release.py）按以下逻辑打分排序：domain精确命中得 18 分、通用平台（all）得 6 分、匹配的产物角色每个加 12 分；当sensitivity为controlled_human且平台是 dbGaP/PhysioNet 时额外加 25 分。返回结果包含recommended_mode、automation_level、recommendation_zh、boundary_zh，供 UI 渲染为"带边界说明的复选框"。

步骤 2：Bind artifacts（绑定产物）

构建open_release_plan.json，包含：项目相对路径、角色、敏感性标签、所选平台、元数据、用户/作者声明、许可、非秘密访问证据。红线：计划中绝不能出现 token、密码、Cookie、会话值或私钥。

计划文件的字段由 open-release-plan.schema.json 强制约束，artifacts[].sensitivity只能是none、deidentified_human、identifiable_human、controlled_human、confidential、restricted、unknown之一；access_evidence[].status只能是available/missing/unknown/expired，source只能是host_probe/browser_probe/user_attestation/institutional_document/platform_response。

源码对"秘密进计划"做了双重拦截：secret_key_paths()递归扫描键名（token、password、secret、cookie、session_cookie、credential_value及_password/_secret后缀），secret_value_paths()用正则识别私钥头（-----BEGIN ... PRIVATE KEY-----）、GitHub token（gh[pousr]_...）、AWS 访问密钥（AKIA...）等模式，发现即产出SECRET_IN_PLAN/SECRET_VALUE_IN_PLAN缺口，且不打印秘密值本身。

步骤 3：Probe permissions（探测权限）

宿主（host）在用户电脑上执行只读检查：已安装的 CLI、已认证的 CLI、已登录的浏览器会话、组织角色、平台资格。计划中只保存capability/status/source/checked_at，绝不含秘密或 Cookie。

接口文档给出了标准的非秘密权限证据条目：

{ "platform": "github", "capability": "github_authenticated", "status": "available", "source": "host_probe", "checked_at": "2026-08-23T10:00:00Z", "evidence_note": "gh auth status succeeded; no token captured" }

注意platform="*"仅允许用于真正的主机级能力（如computer_control），严禁用通配符声称账号、组织、资格或发布权限。

步骤 4：Preflight（预检）

运行preflight，每个平台独立输出一种状态：

• READY_FOR_FINAL_CONFIRMATION（一键就绪）
• READY_FOR_GUIDED_HANDOFF（引导式交接就绪）
• NEEDS_LOGIN_OR_PERMISSION
• NEEDS_ELIGIBILITY
• NEEDS_COMPLIANCE
• NEEDS_METADATA
• NEEDS_ARTIFACT
• BLOCKED

源码preflight()（src/scripts/open_release.py）会按平台逐一校验：元数据必填项、作者/合规声明、模式所需能力（mode_requirements）、绑定产物角色匹配、敏感性合规（可识别/机密/受限产物禁止发往公开平台，除非是受控平台）、许可约束（如 Dryad 要求 CC0）、重复勾选、未知平台等。缺口按 category 归类，最终汇总出四个宏观状态：FULL_BETA_READY（无缺口且无引导式平台）、ASSISTED_RELEASE_READY（无缺口但含引导式平台）、PARTIAL_RELEASE_READY（有就绪子集）、BLOCKED（无可用平台）。

预检结果同时给出结构化信号：full_one_click_beta_available、assisted_release_available、partial_release_possible、manual_handoff_required、can_prepare、can_request_final_confirmation（外部授权恒为false）。

步骤 5：Prepare（准备）

运行prepare进入新的不可变（immutable）运行目录，产出：哈希绑定清单（manifest）、动作清单（action list）、确认请求（confirmation request）、人类可读摘要（human summary）。此步骤不执行任何网络发布。

源码prepare()会先重跑预检并检查can_prepare，然后写入四个文件：open_release_preflight.json、open_release_manifest.json、open_release_actions.json、open_release_summary.md与open_release_confirmation_request.json。清单中的confirmation_id由release_id、计划哈希、就绪平台列表共同派生（SHA-256 截取 24 位十六进制），确认请求里以consequences_zh明确告知用户三个后果：文件将离开本机、公开记录可能永久可见、确认只覆盖哈希/平台/可见性/许可/动作范围完全一致的本次发布。

步骤 6：Final user confirmation（最终用户确认）

向用户展示：精确的平台列表、文件哈希、可见性、许可、每个平台的最大 Agent 动作。用户必须创建一份paperspine.open-release.confirmation，且该确认文件必须绑定清单的 SHA-256。

确认文件字段由 open-release-confirmation.schema.json 约束：confirmed必须为true，manifest_sha256必须是 64 位十六进制，authorized_platforms非空且不重复。接口文档明确要求：确认界面负责生成合法确认 JSON，不要让用户手改；主 UI 只有在预检信号can_request_final_confirmation=true时才应开放最终确认按钮。

步骤 7：Authorize（授权）

运行authorize，对每个产物重新计算哈希。只有哈希匹配的确认才会生成agent_release_ticket.json，并将signals.external_action_authorized置为true。

源码authorize()（src/scripts/open_release.py）的校验清单包括：确认文件 contract、确认中是否混入秘密、confirmed是否为真、确认绑定的 manifest 哈希是否与当前清单一致、confirmation_id是否属于当前 prepare 运行、授权平台是否全部通过预检、部分发布是否被计划与确认同时显式允许（allow_partial_release）、源计划哈希是否漂移、所有产物是否漂移（artifact_drift_gaps()逐一比对 SHA-256、字节数与文件数）。任何一项不满足都返回BLOCKED，外部授权保持false。

生成的 ticket（契约 open-release-agent-ticket.schema.json）为每个授权平台记录精确动作：platform、mode、action_scope、launch_url、artifact_ids、metadata、idempotency_key（由release_id:manifest_hash:platform:scope哈希派生）。authority_boundary被硬编码为：仅精确范围（exact_scope_only=true）、不得接受新费用/许可/声明、不得上传已变更产物、引导式平台不得超出最大动作。

步骤 8：Host execution（宿主执行）

宿主 Agent 使用用户电脑与精确 ticket 执行外部动作，遇到以下任何情况必须暂停并回报用户：

• 新的费用或付款
• 新的许可或条款
• 新的作者声明
• 新的资格或机构审批要求
• 产物漂移（artifact drift）
• 平台要求暴露凭据

步骤 9：Record（记录）

宿主为每个授权平台写一份结构化回执，然后运行record保存：公开 URL、DOI/accession ID、审核状态、失败信息、等待用户状态。绝不把部分成功伪装成全局成功。

源码record()（src/scripts/open_release.py）会校验回执是否绑定 ticket SHA-256、幂等键是否与 ticket 动作一致、每个成功/审核/草稿状态是否携带真实外部记录标识（_has_external_identity()检查public_url/doi/accession/platform_record_id，且 URL 必须有效、DOI 必须匹配10.xxxx/...格式、不允许与通用 launch page 相同）。最后按成功回执数量得出总体状态：全部成功为RELEASE_RECORDED，部分成功为PARTIAL_RELEASE_RECORDED，否则为RELEASE_WAITING_OR_FAILED。

四、预检状态机与权限反馈产品面

参考文档把"权限反馈"定位为**产品表面（product surface）**而非通用异常：

• 每个缺口必须返回：平台、代码、类别、中文解释、恢复负责人/动作/URL、是否可重试；
• 主 UI 在无可安全平台时醒目显示：完整一键开源 Beta 不可用；
• 存在就绪子集时显示：完整一键开源暂不可用，可按授权发布已就绪平台。

三条强制规则：

1. 绝不静默跳过已勾选的平台；
2. 绝不让用户把 token 粘贴进聊天或 JSON；
3. 缺浏览器会话就引导用户在自己浏览器里登录；缺组织/机构角色就定位具体角色，而不是索要更强的个人 token。

源码中gap()工厂（src/scripts/open_release.py）产出的缺口对象正是这一产品面的数据结构：code、platform、category、message_zh、blocks_full_one_click、can_retry、recovery{owner, action_zh, url}；capability_feedback()按能力类型给出针对性中文恢复指引（如缺gh_cli_available提示安装官方 CLI，缺zenodo_token_deposit_write提示在主机凭据存储创建最小权限凭据且不写进 JSON）。markdown_summary()还会把预检结果渲染为带"不含任何 token/密码/Cookie/会话值"声明的摘要。

五、医学与人类数据路由（artifact-specific）

医学发布是按产物类型路由的，参考文档给出了完整路由表，逐行继承如下：

若内置目录未覆盖学科或产物类型，使用 FAIRsharing 与 re3data 做实时仓库发现，研究所选仓库的官方要求，不得发明通用上传路线。这在平台目录中对应两个selectable=false的发现服务条目（fairsharing、re3data），其maximum_agent_action均为recommend_repository——它们是目录而非上传目标。

六、平台目录与自动化等级

平台目录文件 open-release-platforms.json 是"路由证据"而非实时事实：catalog_version/checked_at标记了目录检查日期，source_policy.refresh_rule明确要求每次真实发布前重新核对平台官方要求（账号、政策、文件与资格规则可能在目录日期之后变化）。

每个可勾选平台都包含：kind、domains、artifact_roles、automation_level、recommended_mode/allowed_modes、public_access、maximum_agent_action、required_metadata、required_declarations、mode_requirements、license_constraints、official_urls、recommendation_zh、boundary_zh。目录共收录 20 个可勾选平台 + 2 个发现服务，自动化等级可归纳为四类：

以 GitHub 为例：recommended_mode=agent_cli，CLI 模式要求computer_control、gh_cli_available、github_authenticated、repository_create_permission；必填元数据为repository_owner、repository_name、description、visibility；必填声明为rights_holder_authorized、third_party_assets_cleared、license_confirmed。以 Dryad 为例：许可约束为["CC0"]，且要求human_data_anonymized_if_applicable声明，人类数据必须严格匿名化。这些字段正是预检逐项比对的依据。

七、安全与幂等设计

参考文档的安全与幂等约束，结合源码可归纳为六条可验证机制：

1. 不可变运行目录：prepare/authorize/record的输出目录必须是新目录或空目录（ensure_new_output()强制）；
2. 产物必须在project_root内，拒绝符号链接：resolve_inside()拒绝逃逸路径，hash_path()对符号链接直接抛错；
3. 明显的秘密文件与秘密模式硬阻断预检：.env、id_rsa等密钥文件名、.pem/.p12/.pfx/.key后缀，以及文本内容中的私钥头/GitHub token/AWS 密钥模式，命中即产出POSSIBLE_SECRET_IN_ARTIFACT缺口且不打印值（obvious_secret_files()，1MB 以上二进制文件跳过文本扫描）；
4. 敏感产物不可发往公开仓库：identifiable_human、confidential、restricted状态直接阻断公开平台（PUBLIC_BLOCKING_SENSITIVITY），unknown状态必须完成 PHI/PII、合同、出口管制与第三方权利检查后才能继续；
5. Ticket 绑定一切，文件变化需重新确认：ticket 把 plan、manifest、confirmation、平台、元数据、动作范围与产物哈希绑定在一起；authorize时任何漂移（源计划漂移、产物漂移）都返回BLOCKED并要求重新 prepare + 重新确认；
6. 每个平台动作都有idempotency_key：由release_id:manifest_sha256:platform:action_scope哈希派生，record阶段会验证回执幂等键与 ticket 一致；重试前先读最终回执，不得对已成功平台重复创建记录。

八、完成边界与信号语义

参考文档明确了三个容易误读的状态，这是接入方必须内化的语义：

• FULL_BETA_READY= 预检通过、等待最终确认。它不是发布；
• AGENT_RELEASE_AUTHORIZED= 宿主可以执行 ticket 中的精确外部动作。它不是这些动作已成功的证据；
• RELEASE_RECORDED= 每个授权平台都返回了被接受的回执状态；PARTIAL_RELEASE_RECORDED必须保持可见的部分性，不得被合并为全局成功。

所有操作的结果统一封装为 open-release-result.schema.json 描述的结构：contract、interface_version、request_sha256、operation、ok、outcome、stage、gaps、warnings、artifacts、signals、user_feedback、authority_boundary、audit。接口文档（open-release-interface.md）明确要求：调用方必须消费signals与结构化 gaps，而不是解析 Markdown 摘要。

九、契约 Schema 一览与集成要点

Open Release 的全套契约 Schema 均位于 src/skill/references/contracts/，并与 dist/claude/skills/paper-spine/references/contracts/ 等发行版保持同步（tests/test_skill_structure.py会对这些文件的存在性做结构校验）：

• open-release-invocation.schema.json（请求信封，含按操作的条件必填约束）
• open-release-plan.schema.json（发布计划）
• open-release-manifest.schema.json（prepare 产物清单）
• open-release-confirmation.schema.json（用户最终确认）
• open-release-agent-ticket.schema.json（宿主执行凭据）
• open-release-platform-receipts.schema.json（平台回执，含成功状态的记录标识条件）
• open-release-result.schema.json（统一结果信封）

集成时的四个关键约定：

1. 调用位置：源码调用方用src/scripts/open_release.py，安装版 Skill 用scripts/open_release.py，Python 调用方可用invoke_open_release(request_path)；
2. 消费方式：读signals与gaps，UI 只有在can_request_final_confirmation=true时才开放最终确认按钮；部分发布需要计划与最终确认同时显式设置allow_partial_release=true，且确认只能授权eligible_platforms；
3. 执行守则：宿主对每个ticket.actions[]先查幂等键是否已有成功回执，再打开官方 URL 或已批准的 CLI/API 路线，只上传清单内的产物、只应用 ticket 元数据、绝不超出action_scope，遇到新费用/许可/条款/声明/资格/机构审批/认证或文件变化立即暂停；
4. 目录时效：平台目录的日期只是推荐路由证据，正式执行前必须重新核对所选平台的官方页面。

十、参考文件索引

• 关联参考文档：dist/claude/skills/paper-spine/references/open-release.md（源码侧对应 src/skill/references/open-release.md）
• 集成接口：src/skill/references/open-release-interface.md
• 平台目录：src/skill/references/open-release-platforms.json
• 核心实现：src/scripts/open_release.py
• 技能调用上下文：src/skill/SKILL.md（"Use open-release.md only for explicit release work"）
• 契约目录：src/skill/references/contracts/
• 结构校验：tests/test_skill_structure.py

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用