binder-source

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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）

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

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

## 2 · 锁定 revision（lock）

```bash
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）

```bash
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 并列出已登记的源，不猜测。

## 输出模板

```markdown
## 数据源操作结果：<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）。

From Hylouis233/workbuddy-skills, MIT.

More from Hylouis233/workbuddy-skills