---
name: aDNA-downloader
description: 下载古代 DNA 数据并按指定 Excel 模板整理 metadata。
title: aDNA-downloader
canonical_url: https://skilld.dev/gh/victory-hugo/s2-agent-skill/adna-downloader
last_updated: 2026-10-07T11:02:39.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [assets/1-中国省份规范名称.tsv](https://skilld.dev/api/skills-raw/victory-hugo/s2-agent-skill/adna-downloader/assets/1-中国省份规范名称.tsv), [assets/2-全球国家标准简称.tsv](https://skilld.dev/api/skills-raw/victory-hugo/s2-agent-skill/adna-downloader/assets/2-全球国家标准简称.tsv), [key/1-NCBI-API.key](https://skilld.dev/api/skills-raw/victory-hugo/s2-agent-skill/adna-downloader/key/1-NCBI-API.key), [README.md](https://skilld.dev/api/skills-raw/victory-hugo/s2-agent-skill/adna-downloader/README.md), [template/古代DNA收集模板-AI-agent.xlsx](https://skilld.dev/api/skills-raw/victory-hugo/s2-agent-skill/adna-downloader/template/古代DNA收集模板-AI-agent.xlsx).
>
> If the user asked to install this Skill, run `npx skilld install victory-hugo/s2-agent-skill/adna-downloader`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/adna-downloader`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/victory-hugo/s2-agent-skill/adna-downloader) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/adna-downloader`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/adna-downloader --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/adna-downloader --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 古代 DNA 数据收集与下载 Agent

根据用户提供的文献、PDF、补充材料、数据库编号、链接或关键词，收集**当前研究本身产生**的古代 DNA 样本基础信息和原始测序数据，按模板输出可追溯结果。

## 输入与输出

输入：文献、PDF、补充材料、accession、链接或关键词。

输出目录：

```
output/
├── meta/时间戳.xlsx          # 由模板复制而来
└── data/                     # 数据文件、清单、命令、失败说明
    ├── file_manifest.tsv
    ├── download_commands.sh
    └── download_skipped.tsv  # 未下载时记录
```

## 检索与下载 API 优先原则

直接爬取出版社网页（PDF、正文图表、补充材料）常触发人机验证，应优先走官方 API/程序化接口，仅在 API 均无结果时才尝试直接访问网页，且需在记录中注明可能遇到验证码、访问受限。

### 密钥与联系邮箱

- NCBI 邮箱与 API key 存放于 `key/1-NCBI-API.key`（第一行邮箱，第二行 api_key）。该目录已加入 `.gitignore`，禁止提交到版本库或写入报告正文。
- Crossref、Unpaywall 调用一律带上 `key/1-NCBI-API.key` 中的邮箱（或用户提供的其他联系邮箱）作为 `mailto` / `email` 参数，并在 User-Agent 中注明工具名与该邮箱，以进入 polite pool / 避免被拒绝。

### 检索顺序（按数据类型）

1. **已知 DOI 查元数据**：`https://api.crossref.org/works/{DOI}?mailto=<邮箱>`。
2. **查合法开放获取全文**：`https://api.unpaywall.org/v2/{DOI}?email=<邮箱>`，取 `best_oa_location`/`oa_locations` 中的直链（机构库、Zenodo、Figshare、作者稿等）。
3. **生物医学文献 / PMC 全文包（含图表、补充材料）**：
   - 检索：`https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`、`efetch.fcgi`、`esummary.fcgi`，带 `api_key`、`email`、`tool` 参数。
   - PMC 开放全文包（含正文图表 JATS XML 及可用补充材料）：`https://www.ncbi.nlm.nih.gov/pmc/utils/oa/oa.fcgi?id=<PMCID>`，下载返回的 `.tar.gz`。
   - 无 api_key 时限速 ≤3 次/秒；带 api_key 时 ≤10 次/秒，禁止超过。
4. **正文图表资源（Figure、JATS XML 中的表格、PDF 中的图）**：优先从 PMC 全文包 JATS XML 或出版社 TDM/Crossref `link` 字段中的 XML/PDF 直链获取；缺失时才尝试出版社页面直接抓图。
5. **补充材料文件（xlsx/csv/docx/zip、Supplementary Table/Figure、Figshare/Zenodo 数据）**：
   - 依次尝试：Unpaywall 命中的仓库页面（Zenodo/Figshare/Dryad 等）→ Crossref 元数据中的 `relation`/`link` 字段 → Europe PMC `supplementaryFiles` 接口（见下）→ 出版社自有 ESM 服务器（见下）。
   - **Europe PMC 补充材料接口**（PMC OA 包被验证拦截时的首选替代）：`https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/supplementaryFiles`，返回 zip，通常能绕过 PMC 网页版的人机验证/PoW 挑战，直接拿到图片、SI 说明文档等。
   - **⚠️ 完整性核查（重要，勿漏项）**：Europe PMC / PMC OA 包只包含"存档到 PMC 的部分"（通常是正文图 + SI 说明 PDF/DOCX），**不等于出版社官网列出的全部附件**。数据类大表格（如 Supplementary Table，尤其是 xlsx）出版社常单独托管，不进入 PMC 存档。取得 PMC/Europe PMC 补充材料包后，必须再核对出版社文章页列出的附件清单（数量、文件名、格式），确认两边条目一一对应；有出入（尤其缺少 xlsx/csv 等数据表）时，按下方"出版社 ESM 直链模式"补齐，不能默认 PMC 包已是全集。
   - **出版社 ESM 直链模式**（用于核对/补齐缺失附件，直接请求即可，通常无需人机验证）：
     - **Springer/Nature**：文章页 `https://www.nature.com/articles/{文章ID}`（需带 `mailto:` User-Agent，`curl -sL` 跟随重定向）中搜索 `MediaObjects`/`MOESM` 关键词，可枚举出全部 `MOESM1, MOESM2, …` 附件及其中文描述（如 "Supplementary Tables"）；直链形如 `https://static-content.springer.com/esm/art%3A{URL编码DOI}/MediaObjects/{文章内部ID}_MOESM{N}_ESM.{ext}`。
     - **PLOS**：文章页或 API 中搜索 `journals.plos.org/.../file?id=10.1371/...s{NNN}`，附件命名通常为 `S1 Table`、`S2 Fig` 等。
     - **Wiley**：搜索 `onlinelibrary.wiley.com/action/downloadSupplement`。
     - **Elsevier/Cell Press**：搜索 `ars.els-cdn.com`（Crossref `link` 字段有时也会给出）。
     - 其他出版社未知模式时，直接 `curl -sL` 抓文章页 HTML，用关键词 `supplementary|ESM|MediaObjects|S1_|Table_S|\.xlsx|\.csv` 搜索，而非凭经验猜测跳过。
6. **上述 API 均未命中，或出版社 ESM 直链也拿不到时**：允许尝试直接访问出版社页面完整渲染版本，但须在 `download_skipped.tsv` 或复核记录中注明"API 未命中，尝试直接访问"及最终结果（含遇到人机验证/PoW 挑战的情况，以及已尝试过的具体接口列表，避免下次重复踩坑）。

### 限速与容错

- 对同一域名的请求做基本限速（Crossref/Unpaywall 建议顺序请求，不并发轰炸）和失败退避（如遇 429，等待后重试，不重复硬闯）。
- 对已查询过的 DOI/PMCID 结果可在当次任务内复用，避免重复请求。

### 补充材料清单核对（工作流硬性步骤）

在写入 `Citation_short` sheet 前，必须先列出"出版社官网声明的附件总数与类型"（从文章页 Supplementary Information 区块解析，如 "Supplementary Information / Reporting Summary / Supplementary Tables / Peer Review File" 各几份、什么格式），再与已下载/已获取的文件逐一核对是否齐全，在 `Citation_short` 中如实记录：
- 出版社声明的附件清单（编号、文件名、格式、内容简介）；
- 每项是否已获取、通过哪个接口获取、未获取的原因；
- 若数据类附件（xlsx/csv 等 Supplementary Table）缺失，禁止仅凭 PDF 版 Supplementary Information 就判定"已完整收集"，须明确标注待补齐。

## 核心原则

1. **模板不可变**：必须复制 `template/古代DNA收集模板-AI-agent.xlsx` 后再写入；保留字段、顺序、格式、公式、数据验证、下拉框、隐藏 sheet、命名区域，以及模板 sheet 第二行原始注释行。禁止用 `pandas.to_excel()` 等方式覆盖结构。
2. **任务范围**：除非用户明确说明"仅收集基础信息"或"仅下载原始数据"，**默认同时完成两项**。
3. **数据范围**：只处理当前研究产生的数据，禁止纳入引用的其他研究、参考、比较或对照数据。
4. **来源优先级**：用户主动提供 PDF/补充材料时，基础信息必须优先从中提取；仅当用户资料缺失或无法确认时才查外部来源；冲突时以用户资料为准，并在复核记录注明。
5. **禁止编造与留空**：具体缺失值、必填/选填、格式要求以模板第二行注释为准；下拉字段的允许值以模板数据验证列表为准（`openpyxl` 写入不会触发 Excel 校验，禁止凭经验写同义词、缩写、翻译或新类别），缺失时记录复核原因。
6. **特殊字段**：
   - 样本来自中国时，省份使用 `assets/1-中国省份规范名称.tsv` 中的 `省份英文名称_标准`。
   - 国家`Country`列需要使用 `assets/2-全球国家标准简称.tsv` 中的 `国家(英文标准)`。
   - `Latitude` / `Longitude` 禁止填 `Unknown` 或留空；若原文无坐标，**自行搜索**遗址经纬度并在复核记录注明来源。

## Genetic_ID 规则（单一权威定义）

`Genetic_ID` 是**文件级遗传数据 ID**，对应 BAM / CRAM / FASTA / FASTQ / VCF / BCF / BED / EIGENSTRAT 等原始数据文件。

### 提取优先级

1. 研究发布的数据文件名主体（去目录路径，保留可唯一识别 ID）。
2. 数据库清单中的 submitted / fastq / bam / analysis file name 或 FTP 文件名。
3. 数据库仅给 run accession 且 FASTQ 由 run 生成时，使用实际 FASTQ 文件名主体（如 `SRRxxxxxxx_1`、`SRRxxxxxxx_2`），并在 `Citation_short` 注明推导依据。
4. 仍无法确认时，写 `UNRESOLVED_FILE_ID__<Run_accession或样本号>`，记录已检索的数据库、字段、链接、失败原因，并标记人工复核。

### 检索强制性

**即使用户说"不必下载"，也必须检索数据库记录、文件清单、run table、manifest 或 data availability 来确认文件级 ID。"不下载"仅指不取回大文件，不允许跳过 ID 核验。**

### 多文件处理

- 成对 FASTQ：填两个文件主体，英文 `;` 分隔；或按模板粒度拆多行，并在复核记录注明。
- 多 lane / library / run：保留全部可追溯 ID，禁止合并为样本号。
- `Run_accession`、`BioSample_accession`、`BioProject_accession`、`Library_ID` 只作辅助字段，仅当它们就是实际文件名主体时方可作为 `Genetic_ID`。

### file_manifest 强制记录

写入 `Genetic_ID` 前必须先在 `output/data/file_manifest.tsv` 建立记录，至少包含：
`Genetic_ID`、`Master_ID`、`Library_ID`、`Run_accession`、`Source_database`、`Origin_data_class`、`file_name_original`、`file_url_or_accession`、`database_record_checked`、`download_status`、`review_note`。

每条 `总表` 记录的 `Genetic_ID` 必须能在 `file_manifest`、实际下载文件、下载命令或失败说明中找到一一对应证据。

## 工作流程

### 1. 初始化

创建 `output/meta/` 和 `output/data/`，复制模板生成 `output/meta/时间戳.xlsx`。

### 2. 读取模板结构

读取 `模板` sheet 的字段名、字段顺序、第二行说明、格式、公式、数据验证、下拉框、隐藏 sheet、命名区域，确保后续写入不破坏这些元素。

### 3. 收集基础信息

#### 检索顺序

用户已提供 PDF / 补充材料时：

1. 补充材料附表（附表 1、2、3…）
2. 文章 PDF 表格（表 1、2、3…）
3. 补充材料正文、方法、图表注释
4. 文章 PDF 正文、方法、结果、数据可用性声明
5. 用户资料中的 accession、链接、对照表

用户未提供或上述资料无法确认字段时，再查外部数据库、网页等。

#### 写入要求

- 标准化信息写入 `总表`，每条记录可追溯。
- 每篇文献 / 数据来源新建一个 `Citation_short` sheet，保存原始表格、数据库记录、链接、accession、文件信息、原文描述、复核与排除记录。
- 来自用户资料的信息必须记录文件名、页码、表号、附表名、行号、列名等定位信息。
- 每个字段记录：是否检索、是否命中、提取字段、原始字段名、原文值、标准化值、未命中原因、是否来自用户资料、是否需复核。

### 4. 处理原始遗传数据

先按 [Genetic_ID 规则](#genetic_id-规则单一权威定义) 完成文件级 ID 检索，再按以下模式输出：

- **下载模式**：用户指定格式优先；未指定时 BAM / CRAM 优先，其次 FASTQ / FASTA / 其他；保存到 `output/data/`。
- **不下载模式**：仍必须输出 `file_manifest.tsv`、`download_commands.sh` 或 `download_skipped.tsv`，包含文件级 ID、文件名、URL / accession、来源数据库、检索时间、未下载原因。
- **下载失败**：保存 accession、文件级 ID、命令和失败说明。

### 5. 质量检查

完成前逐项核对：

- [ ] Excel 文件存在且包含 `总表`
- [ ] 模板第二行注释、字段、格式、公式、数据验证、隐藏内容均保留
- [ ] 下拉框字段全部为模板允许值
- [ ] 无空白字段
- [ ] `Genetic_ID` 均对应文件、清单、命令或失败说明
- [ ] 即便不下载，也已完成数据库检索确认 `Genetic_ID`
- [ ] 未把 `Master_ID`、`Skeletal_ID`、`Library_ID`、`Run_accession`、`BioSample_accession`、`BioProject_accession` 错填为 `Genetic_ID`
- [ ] `file_manifest` 含每条 `总表` 记录的文件级证据
- [ ] 已排除非当前研究的引用 / 对照数据
- [ ] 用户未限定范围时，基础信息和原始数据均已处理
- [ ] 用户提供资料已优先使用，外部补充均记录原因与复核说明
- [ ] `Latitude` / `Longitude` 无空白、无 `Unknown`

## 最终报告

仅列出：

- Excel 文件路径
- 数据目录路径
- 已处理文献 / 数据来源数
- 已整理记录数
- 已下载、未下载、受限、失败的数据数
- 已排除的非当前研究数据数
- 需人工复核的字段或问题
- 用户提供资料使用情况
- 外部来源补充使用情况
