qPTM Collection Agent

用专用 LLM 链 + 确定性编排，从海量 PubMed 摘要中挖掘**定量蛋白质修饰组学（PTMomics）**文献，并逐步落到 qPTM 库可用的定量表。

设计原则：学 L2M3 的「专用链 + 编排」，不用 Coding Agent 做全自动挖矿；Pi 仅作 ModelRuntime 底座。

当前范围：Stage 1–6（到 MS 原始数据下载链接解析）。Stage 7（MaxQuant 搜库等）暂不做。

Pipeline 总览

data/abstracts/*.csv
        │
        ▼
┌─────────────────┐
│ Stage 1 Screen  │  摘要筛选 → include / exclude / uncertain
└────────┬────────┘
         │ stage1_include_pmids.csv
         ▼
┌─────────────────┐
│ Stage 2 Fetch   │  Discover 仓库号 + 合法 OA 全文
└────────┬────────┘
         │ fulltext + identifiers
         ▼
┌─────────────────┐
│ Stage 3 Meta    │  实验元数据 → literature_info 格式
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Stage 4 Route   │  Supp / PRIDE / 正文表 路由（Supp Scout 已实现）
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Stage 5 Parse   │  定量表 → qratio schema（启发式 + LLM 列映射）
└────────┬────────┘
         │ qratio_success.csv
         ▼
┌─────────────────┐
│ Stage 6 URLs    │  Stage3 MS 源 + Identifier → 原始数据下载链接
└─────────────────┘

Stage	状态	作用	主要输入	主要输出
1 Screen	✅ 已实现	摘要级 include/exclude	`data/abstracts/*.csv`	`data/stage1/stage1_*.csv`
2 Fetch	✅ Discover + OA Fulltext	仓库号 + 合法 OA 全文	`stage1_include_pmids.csv`	`data/stage2/`
3 Meta	✅ MetaChain	抽实验元数据	Stage 2 全文 + identifiers	`data/stage3/literature_info.csv`
4 Route	✅ Supp Scout	侦察 OA Supplementary 定量表线索	全部 Stage 3	`data/stage4/supp_scout.*` / `supp_jobs.jsonl`
5 Parse	✅ Qratio Parse	解析定量表（先 likely 189）	Stage 4 jobs + ZIP	`data/stage5/qratio.csv`
6 URLs	✅ MS Download	解析 PRIDE/iProX/jPOST 原始数据链接	Stage5 success + Stage3 MS 信息	`data/stage6/download_jobs.csv`, `urls_all.csv`

Schema 参考：

Stage 3 目标：files/qPTM3_109pmids.csv（Sample、PTMs、Label method、MS data source、Identifier…）
Stage 5 目标：files/example_qratio.csv（UniProtID、Position、Log2Ratio、p-value…）
Stage 6 产物：data/stage6/urls/{pmid}#{accession}#{organism}#{modification}.txt（每行一个下载 URL）

目录结构

CollectionAgent/
├── data/
│   ├── abstracts/              # Stage 1 输入（PubMed 导出摘要）
│   │   ├── phosphorylation.csv
│   │   ├── ubiquitylation.csv
│   │   ├── lipidation.csv
│   │   └── lysine.csv
│   ├── stage1/                 # Stage 1 输出
│   ├── stage2/                 # Stage 2 输出（Discover + fulltext）
│   ├── stage3/                 # Stage 3 输出（literature_info）
│   ├── stage4/                 # Stage 4 输出（supp scout）
│   ├── stage5/                 # Stage 5 输出（qratio）
│   ├── stage6/                 # Stage 6 输出（MS 下载链接）
│   ├── eval/                   # 评估金标准与报告
│   │   └── gold/
├── files/                      # 静态参考 / 示例 schema
├── src/
│   ├── chains/screen/          # Stage 1 ScreenChain
│   ├── chains/meta/            # Stage 3 MetaChain
│   ├── pipeline/stage1.ts
│   ├── pipeline/stage2*.ts
│   ├── pipeline/stage3.ts
│   ├── pipeline/stage4-supp.ts
│   ├── pipeline/stage5.ts
│   ├── pipeline/stage6.ts
│   ├── stage6/                 # PRIDE / iProX / jPOST 解析客户端
│   ├── eval/stage1-recall.ts
│   └── index.ts                # CLI
└── skills/qptm-screen/         # Stage 1 筛选准则备忘

Stage 1 输入文件命名

文件	原名（已弃用）	内容侧重
`data/abstracts/phosphorylation.csv`	`磷酸化等.abstract-post-trans-set.csv`	磷酸化等
`data/abstracts/ubiquitylation.csv`	`类泛素化修饰.abstract-post-trans-set.csv`	类泛素化
`data/abstracts/lipidation.csv`	`脂化修饰.abstract-post-trans-set.csv`	脂化
`data/abstracts/lysine.csv`	`赖氨酸修饰.abstract-post-trans-set.csv`	赖氨酸修饰

同一 PMID 可出现在多个 CSV；加载时按 PMID 去重。

环境

Node.js ≥ 22.19
在 .env 配置模型密钥。推荐 OpenCode Go（订阅即可用 DeepSeek V4 Flash 等）：

OPENCODE_API_KEY=sk-...          # https://opencode.ai/auth
MODEL=opencode-go/deepseek-v4-flash
UNPAYWALL_EMAIL=you@example.com  # Stage 2 Unpaywall 需要
# Optional — Stage 1 PubMed 摘要拉取（E-utilities）
# NCBI_API_KEY=...
# NCBI_EMAIL=you@example.com

也支持直接 DeepSeek / Anthropic / OpenAI / Google（见 .env.example）。若只配了 OPENCODE_API_KEY 而 MODEL=deepseek/deepseek-v4-flash，运行时会自动改走 opencode-go。

npm install

若系统 PATH 无 npx，可临时加上本机 Node bin（例如 Zed 自带 Node）。

CLI 用法（Stage 1）

筛选

# 全库待筛（跳过已写入 stage1_results 的 PMID）
npx tsx src/index.ts screen --all --concurrency 4

# 仅 PMID 列表（自动从 PubMed / PubTator3 拉摘要；可无本地 abstracts CSV）
# --validation：结果写入 validation/stage1 … 不污染 data/
npx tsx src/index.ts screen --pmids-file validation/validation_data.csv --all --concurrency 2 --validation
npx tsx src/index.ts screen --pmid 36593272
npx tsx src/index.ts screen --pmids-file validation/validation_data.csv --abstract-source pubtator3 --all --validation

# 限制条数 / 单文件
npx tsx src/index.ts screen --limit 20 --concurrency 1
npx tsx src/index.ts screen --all --file phosphorylation --concurrency 4
npx tsx src/index.ts screen --all --file ubiquitylation --concurrency 4
npx tsx src/index.ts screen --all --file lipidation --concurrency 4
npx tsx src/index.ts screen --all --file lysine --concurrency 4

选项	说明
`--all`	处理全部 pending（忽略 `--limit`）
`--limit <n>`	本轮最多 n 篇（默认 20）
`--file <name>`	`sourceFile` 子串匹配，如 `phosphorylation`
`--pmid <id>`	单篇 PMID；本地无摘要时自动 API 拉取
`--pmids-file <path>`	PMID 列表 CSV（仅需 PMID 列）或纯文本一行一个
`--abstract-source`	`pubmed` / `pubtator3` / `auto`（默认：先 PubMed，缺则 PubTator3）
`--out-dir <path>`	阶段输出根目录（默认 `data/`）
`--validation`	等价于 `--out-dir validation`
`--concurrency <n>`	并行 LLM 调用
`--flush-every <n>`	每 n 条落盘
`--model <id>`	覆盖默认模型
`--skip-gold`	跳过 `0_literature_info.csv` 中已有 PMID

拉取到的摘要会缓存到 <out>/abstracts/api_fetched.csv（默认 data/abstracts/；--validation 时为 validation/abstracts/）。仍可读生产库 data/abstracts/ 作本地缓存。NCBI E-utilities 建议在 .env 配置 NCBI_API_KEY 与 NCBI_EMAIL（也可用 UNPAYWALL_EMAIL）。

Validation 联调（推荐）

用 validation/validation_data.csv 跑通 Stage1–6，结果落在 validation/，与生产 data/ 隔离。

测 Stage2–6（强制全部进下游，跳过 ScreenChain）：

npx tsx src/index.ts screen --pmids-file validation/validation_data.csv --force-include --validation
npx tsx src/index.ts stage2 --all --resume --concurrency 2 --validation
npx tsx src/index.ts stage2-fulltext --all --resume --concurrency 2 --validation
npx tsx src/index.ts stage3 --all --concurrency 2 --validation
npx tsx src/index.ts stage4-supp --all --concurrency 2 --validation
npx tsx src/index.ts stage5 --likely-only --all --resume --concurrency 2 --validation
npx tsx src/index.ts stage6 --all --concurrency 2 --validation

测 Stage1 筛选本身（走 LLM）：

npx tsx src/index.ts screen --pmids-file validation/validation_data.csv --all --concurrency 2 --validation

输出结构：

validation/
├── validation_data.csv          # 输入 PMID 列表
├── abstracts/api_fetched.csv    # 本轮拉取的摘要缓存
├── stage1/ …
├── stage2/ …
├── stage3/ …
├── stage4/ …
├── stage5/ …
└── stage6/ …                 # download_jobs.csv, urls/, cache/

统计

npx tsx src/index.ts stats
# 或
npm run screen:stats

人工复核 uncertain

编辑 data/stage1/stage1_manual_review.csv：

PMID,decision,note
40515996,exclude,method paper
41297956,include,

应用并重导 include / uncertain 列表：

npm run apply-review
# 或
npx tsx src/index.ts apply-review --file data/stage1/stage1_manual_review.csv

Recall 评估

npm run eval:recall
# 默认金标准：data/eval/gold/eval_stage1_include_732pmids.csv
npx tsx src/eval/stage1-recall.ts --concurrency 4 --resume

各 Stage 路径约定

Stage 1（已实现）

角色	路径
输入摘要	`data/abstracts/*.csv`（列：PMID, Title, Abstract）；或 `--pmid` / `--pmids-file` 自动拉取
API 缓存	`data/abstracts/api_fetched.csv`（PubMed / PubTator3 拉取结果）
全量结果	`data/stage1/stage1_results.jsonl` / `.csv`
Include 清单	`data/stage1/stage1_include_pmids.csv`（含 Abstract，Stage 2 唯一输入）
Uncertain 清单	`data/stage1/stage1_uncertain_pmids.csv`
人工复核表	`data/stage1/stage1_manual_review.csv`
运行日志	`data/stage1/stage1_run.log`
Gold include	`data/eval/gold/eval_stage1_include_732pmids.csv`
Recall 报告	`data/eval/eval_stage1_include_732pmids_recall.json`
逐条评估	`data/eval/eval_stage1_include_732pmids_results.{csv,jsonl}`

Stage 2（Discover + OA Fulltext）

角色	路径
输入	`data/stage1/stage1_include_pmids.csv`（唯一输入；含 Abstract）
Discover manifest	`data/stage2/manifest.jsonl` / `stage2_results.csv`
Discover 人工队列	`data/stage2/manual_queue.csv`（无仓库号）
全文目录	`data/stage2/fulltext/{pmid}/fulltext.xml\|pdf` + `meta.json`
全文结果	`data/stage2/fulltext_manifest.jsonl` / `fulltext_results.csv`
全文人工队列	`data/stage2/fulltext_manual_queue.csv`（非 OA / 下载失败）

Discover（找 PXD/IPX/JPST/MSV/PDC）：

Abstract / Title / reason 正则
Europe PMC → DOI/PMCID；PRIDE×DOI；MassIVE / ProteomeXchange；校验 iProX/jPOST
Europe PMC 全文 XML / DOI HTML 再抽号

Fulltext（合法 OA only，不绕付费墙）：

有 PMCID → Europe PMC JATS XML + PDF
仍无 PDF → Unpaywall（需 .env 中 UNPAYWALL_EMAIL）
失败 → fulltext_manual_queue.csv（机构权限手工补）

# Discover
npm run stage2:pilot
npx tsx src/index.ts stage2 --all --concurrency 2 --resume

# Fulltext 试点 / 全量
npm run stage2:fulltext:pilot
npx tsx src/index.ts stage2-fulltext --all --concurrency 2 --resume
npx tsx src/index.ts stage2-fulltext --all --concurrency 2 --retry-unavailable
npx tsx src/index.ts stage2-fulltext --pmid 38101750

Stage 3（Meta → literature_info）

角色	路径
输入	`data/stage2/fulltext/{pmid}/`（优先 XML）+ Stage 2 identifiers + Stage 1 Abstract
全量结果	`data/stage3/stage3_results.jsonl` / `.csv`
标准导出	`data/stage3/literature_info.csv`（对齐 `files/qPTM3_109pmids.csv`）
人工复核	`data/stage3/manual_queue.csv`（partial / 低置信度 / error）

Sample 范围：只填实际做了修饰位点定量 MS的生物材料（与 Condition / 位点定量表同源），不要把文中仅用于表型、WB、非 PTM 组学等的细胞系/组织一并写进 Sample。能确定单一材料时优先填一个；多材料各自有 PTM 位点定量时才用 ; 连接。

Condition：优先写成生物学可读的 Treatment/Baseline（可参考 Detail condition，如 6 h cerebral ischemia/Sham），避免 sheet 缩写名。Stage5 解析后会将表头推导的对比写入 parse_report.csv 的 conditionRefined 列（不修改 Stage3 输出）；需要时可手动运行 npx tsx src/stage5/sync-stage3-from-qratio.ts 回填 Stage3。

npx tsx src/stage5/sync-stage3-from-qratio.ts --validation

文本来源：有 fulltext.xml → 抽 Methods/Experimental + Data availability；仅 PDF → pdfjs-dist 抽正文再截 Methods 窗口；都失败才退回 Abstract。

# 单篇调试（金标准 PMID）
npx tsx src/index.ts stage3 --pmid 38101750

# 试点 / 全量（自动跳过已写入 stage3_results 的 PMID）
npm run stage3:pilot
npx tsx src/index.ts stage3 --all --concurrency 4
npx tsx src/index.ts stage3 --all --concurrency 4 --xml-only
# PDF-only（已完成 XML 的会自动跳过）
npx tsx src/index.ts stage3 --all --concurrency 4

Stage 4（Supplementary 侦察）

对 全部 Stage 3 文献（不论是否已有质谱库 Identifier / PXD/IPX/MSV）侦察 Supplementary：

有 PMCID → Europe PMC OA supplementaryFiles ZIP
否则 / Europe PMC 失败 → 用 DOI 打开出版社页面，解析并下载 ESM / xlsx / csv / zip（Nature/Springer static-content 等）

角色	路径
输入	Stage 3 全量 + 本地 XML + Europe PMC / DOI publisher
侦察结果	`data/stage4/supp_scout.jsonl` / `.csv`
待解析队列	`data/stage4/supp_jobs.jsonl`（`likely_qptm_table` + `has_tabular_supp`）
人工队列	`data/stage4/manual_queue.csv`
下载缓存	`data/stage4/supp/{pmid}/supplementary.zip`（DOI 源另有 `files/`）

npm run stage4:supp:pilot
npx tsx src/index.ts stage4-supp --all --concurrency 2
# 单篇重跑（清缓存并走 DOI fallback；validation 加 --validation）
npx tsx src/index.ts stage4-supp --pmid 35761067 --validation
# 仅缺质谱库号的子集
npx tsx src/index.ts stage4-supp --all --missing-id-only --concurrency 2

Stage 5（qratio 解析）

解压 Stage 4 ZIP → 启发式/LLM 列映射 → example_qratio 行。默认可先 --likely-only，再 --all-jobs。

入库门禁（QC 硬规则）

必须有 Position + AminoAcid（位点级）；蛋白水平定量不要进 qratio.csv
必须有真 qratio（ratio / log2FC / fold-change）；禁止把强度写成假 Log2Ratio
相对定量强度（intensity / abundance / 时间点通道）→ 篇级进 intensity_queue，后续另算 qratio
Condition 对齐 Stage3 literature_info（sample/condition）；缺 UniProt 时可用 gene→UniProt（UniProt REST + 本地缓存）
多 sheet 合并：同一篇多个互补位点表（不同时间点/对比）会合并进 qratio，而不是只留一张表
同篇全蛋白组定量：解析蛋白水平 ratio/FC 后，按 UniProt（+ Condition）回填到位点行的 Log2Ratio (protein) / P value (protein)。只有蛋白组、没有修饰位点的蛋白不入库；无位点修饰表不得当成蛋白组

角色	路径
输入	`data/stage4/supp_jobs.jsonl` + `supp/{pmid}/supplementary.zip` + Stage 3
表清单	`data/stage5/inventory/{pmid}.json`
结果	`data/stage5/stage5_results.jsonl` / `parse_report.csv`
原始解析	`data/stage5/qratio.csv`（含 peptide + 回填的 protein 列）
成功入库篇	`data/stage5/qratio_success.csv`（status=ok 且 rowCount>0）
入库候选	`data/stage5/qratio_clean.csv`（有效 UniProt + 位点 + peptide Log2Ratio；数值列保留 2 位小数）
过滤报告	`data/stage5/qc_filter_report.csv`
强度队列	`data/stage5/intensity_queue.csv`
QC 抽样	`data/stage5/qc_sample.csv` + `scripts/qc_sample_rows.py`
人工队列	`data/stage5/manual_queue.csv`（含 `intensity` / `manual`）

# 单篇 / 试点 / 全量
npx tsx src/index.ts stage5 --pmid 20797632
npm run stage5:pilot
npx tsx src/index.ts stage5 --likely-only --all --concurrency 2 --resume
npx tsx src/index.ts stage5 --all-jobs --all --concurrency 2 --resume

# QC 抽行 + 硬过滤出 clean / intensity_queue
npm run stage5:qc-rows
python3 scripts/stage5_qc_filter.py

Stage 6（MS 原始数据下载链接）

对 Stage5 成功入库（qratio_success.csv，status=ok 且 rowCount>0）的文献，从 Stage3 literature_info.csv 读取 MS data source 与 Identifier，按仓库类型解析原始质谱文件下载 URL。

输入

来源	字段
`stage5/qratio_success.csv`	待处理 PMID 列表
`stage3/literature_info.csv`	`MS data source`、`Identifier`（可多号 `;` 分隔）、`Organism`、`PTMs`

--pmid 单篇调试时，若该 PMID 不在 qratio_success 中但 literature_info 有 Identifier，也会处理（便于测 iProX 子项目等）。

按仓库解析

仓库	方式	下载 URL 来源
PRIDE (PXD)	PRIDE API 定位 FTP 目录 → 下载 listing HTML → `1_html_pride_extract.py`	`https://ftp.pride.ebi.ac.uk/...`
iProX 主项目 (IPX)	`http://download.iprox.org/{IPX}/PX_{IPX}.xml` → `2_xml_iprox_extract.py`	XML 内 `download.iprox.org` 链接
iProX 子项目 (IPX)	`PMD009Controller/findBySubProjectId.jsonp`（子项目页同款 API）	`http://download.iprox.org/{parent}/{sub}/{file}`
jPOST (JPST)	`GET repository.jpostdb.org/_api/file` 分页（`offset` / `num` / `target=public`）	`https://storage.jpostdb.org/{JPST}/{fileName}`

说明：

jPOST 项目页是 SPA，单页 HTML 不含完整 fileLink；必须用 /_api/file 翻页（3_html_jpost_extract.py 仅适合浏览器手动另存的分页 HTML）。
iProX 子项目 ID（如 IPX0006076001）在 getProjectDataFileByProjectId 会返回 NO_SUPPORTED_DATA，需走子项目 API；父项目如 IPX0006076000。
PRIDE / iProX 主项目仍依赖外部脚本目录 ../qPTM3_DataCollection/get_url/（QPTM3_GET_URL_DIR 或 --get-url-dir）。

角色	路径
输入	`stage5/qratio_success.csv` + `stage3/literature_info.csv`
逐篇结果	`stage6/stage6_results.jsonl`
任务明细	`stage6/download_jobs.csv`
全量 URL 表	`stage6/urls_all.csv`（含 `is_raw`）
按篇/按号	`stage6/urls/{pmid}#{accession}#{organism}#{modification}.txt`
缓存	`stage6/cache/{accession}/`（HTML / XML / API JSON）

CLI 选项

选项	说明
`--all`	处理全部 `qratio_success` 文献
`--limit <n>`	批量大小（默认 20；`--all` / `--pmid` 时忽略）
`--pmid <id>`	单篇；可回退到 `literature_info`
`--concurrency <n>`	并行篇数（默认 2）
`--resume`	跳过已在 `stage6_results.jsonl` 的 PMID（默认开）
`--no-resume`	强制重拉
`--get-url-dir <path>`	`get_url` 脚本目录
`--validation`	输出到 `validation/stage6/`

环境变量（可选）：

QPTM3_GET_URL_DIR — 覆盖 get_url 脚本路径
IPROX_USERNAME — 在 notes 中生成 iProX Aspera 批量下载路径（见 iProX helpApi）

# validation：8 篇 PRIDE 成功文献全量
npx tsx src/index.ts stage6 --all --concurrency 2 --validation
npm run stage6:all -- --validation

# 单篇 PRIDE
npx tsx src/index.ts stage6 --pmid 38670996 --validation

# 单篇 iProX 子项目（不在 qratio_success 也可测）
npx tsx src/index.ts stage6 --pmid 39030363 --no-resume --validation

# 单篇 iProX 主项目
npx tsx src/index.ts stage6 --pmid 39012622 --no-resume --validation

架构要点

生产路径：ScreenChain（src/chains/screen）→ runStage1Screen（src/pipeline/stage1.ts）
LLM：Pi ModelRuntime.completeSimple（见 src/runtime.ts）
断点续跑：已写入 stage1_results.jsonl 的 PMID 自动跳过
Prompt 变更：对已有结果使用 --rescreen（配合 --pmid / --pmids-file）清除旧决策后重筛

筛选准则详见 skills/qptm-screen/SKILL.md 与 src/chains/screen/prompt.ts。

npm scripts

npm run screen          # Stage 1 筛选
npm run screen:stats    # 统计
npm run apply-review    # 应用人工复核
npm run eval:recall     # Stage 1 recall
npm run stage2:pilot    # Stage 2 Discover 试点
npm run stage2:fulltext:pilot
npm run stage3:pilot    # Stage 3 Meta 试点
npm run stage4:supp:pilot  # Stage 4 Supp 侦察试点
npm run stage5:pilot       # Stage 5 qratio 试点（likely 10）
npm run stage5:qc-rows     # 从 qratio 按 qc_sample 抽行
npm run stage5:qc-filter   # 生成 qratio_clean.csv
npm run stage6             # Stage 6 MS 下载链接（默认 limit 20）
npm run stage6:all         # Stage 6 全量 qratio_success
npm run smoke:io        # 数据加载冒烟

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

qPTM Collection Agent

Pipeline 总览

目录结构

Stage 1 输入文件命名

环境

CLI 用法（Stage 1）

筛选

Validation 联调（推荐）

统计

人工复核 uncertain

Recall 评估

各 Stage 路径约定

Stage 1（已实现）

Stage 2（Discover + OA Fulltext）

Stage 3（Meta → literature_info）

Stage 4（Supplementary 侦察）

Stage 5（qratio 解析）

Stage 6（MS 原始数据下载链接）

架构要点

npm scripts

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
data		data
files		files
scripts		scripts
skills		skills
src		src
validation		validation
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

qPTM Collection Agent

Pipeline 总览

目录结构

Stage 1 输入文件命名

环境

CLI 用法（Stage 1）

筛选

Validation 联调（推荐）

统计

人工复核 uncertain

Recall 评估

各 Stage 路径约定

Stage 1（已实现）

Stage 2（Discover + OA Fulltext）

Stage 3（Meta → literature_info）

Stage 4（Supplementary 侦察）

Stage 5（qratio 解析）

Stage 6（MS 原始数据下载链接）

架构要点

npm scripts

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages