hylouis233/open-protein-binder-design/binder-source

binder-source：数据源登记与白名单下载

目的

binder campaign 的一切分析都从"数据从哪来、锁在哪个版本、哪些文件允许落地"开始。本技能把这条纪律固化下来：源以 YAML manifest 登记在 sources/（名称、HF 仓库、pinned revision、license、attribution、下载策略），远端文件列表只读 inspect，revision 用 lock 钉死，下载只放行白名单内的小文件。它保证后续 replay / audit 引用的每一个字节都能回溯到一个 pinned revision 和一条 provenance 记录。

前置检查

1. 确认本仓库已安装：pip install -e ".[dev]"，openbinder --help 可用（或 python -m openbinder）。
2. 确认源已登记：openbinder source list 应列出目标 source_id（当前为 anthropic-claude-binder-v1）。未登记的源不能靠猜名字使用。
3. inspect / lock / download 需要网络访问 Hugging Face；离线环境下它们会以结构化错误失败（exit 2），这不是 bug，不得把失败当成"源不存在"。只有 source list 是纯本地的。
4. 产物落盘目录遵循 output/binder-source/<slug>/<timestamp>/；slug 由项目名确定，timestamp 每次运行一个。

1 · 查看与检查（list / inspect）

openbinder source list
openbinder source inspect anthropic-claude-binder-v1 --json

• inspect 是只读操作：列出 pinned revision 下的远端文件清单与字节估计，不下载任何内容。
• 注意 size_unknown 计数：大小未知的文件在下载策略里一律被拦（见下），inspect 时就要看清哪些文件后续不可下载。

2 · 锁定 revision（lock）

openbinder source lock anthropic-claude-binder-v1 --out source.lock.json

• 把当前远端 revision 钉进 source.lock.json，并写入 provenance；此后所有引用都以该 revision 为准。
• 发布方还在上传时（当前现状：data/tables/、data/docs/、data/manifests/ 在 pinned revision 不存在），lock 到的就是不完整的版本——如实记录，等上传完成后重新 lock，绝不用旧 revision 冒充完整版。

3 · 白名单下载（download）

openbinder source download anthropic-claude-binder-v1 data/README.md --dest output/binder-source/<slug>/<timestamp>/

下载策略（deny-by-default，定义在源 manifest 的 download_policy）：

• 只放行 allowed_files 白名单（精确路径 + fnmatch 模式）内的文件；
• blocked_patterns（*.pdb、*.pae*、*sensorgram*、weights 等）在任何情况下不可下载；
• 单文件 ≤ 20 MB、会话累计 ≤ 50 MB、大小未知的文件一律拒绝；
• 违反任何一条返回结构化 blocked 错误（exit 2），包含被拒原因——永不静默绕过，也不得建议用户改策略绕过去；
• 每一笔实际下载都带字节数登记进 .openscience/provenance.jsonl（7 字段契约）。

4 · 失败语义（必须原样转述给用户）

• blocked：策略拒绝，是纪律生效，不是故障；报告被拒的文件与规则。
• unavailable / 网络失败：源当前不可达或文件在 pinned revision 不存在，是 source gap，报告为 unavailable，绝不当作阴性结果（"没下到" ≠ "没有"）。
• 未知 source_id：exit 2 并列出已登记的源，不猜测。

输出模板

## 数据源操作结果：<source_id>
 
-操作：list / inspect / lock / download
-revision：<pinned revision 或 unresolved>
-落地文件：<路径 + 字节数>（无下载则写"未下载任何文件"）
-策略拦截：<被 blocked 的文件与原因；无则写"无">
-provenance：`.openscience/provenance.jsonl` 已登记 / 未产生写操作
-风险与缺口：<如 tables 仍 unavailable、N 个文件大小未知不可下载>

本技能不做什么

• 不批量下载：不做数据集克隆、不碰 PDB/PAE/sensorgram 原始档案，白名单之外一律拒绝。
• 不修改源 manifest 来"方便"下载：策略变更是仓库级决策，不在技能执行中顺手改。
• 不把下载失败解释成数据不存在：failed lookup 是 source gap，不是阴性。
• 不登记假 provenance：没有实际发生的下载不写字节数记录。

收尾与下一步

• 向用户报告 revision、落地文件、被拦截项与缺口；提示 tables 类内容当前 unavailable 时，说明"等发布方完成上传后重新 source lock"。
• 下一步通常是 binder-protocol（把协议草稿编译成结构化 protocol）或 binder-replay（基于已锁定源回放 campaign）。