中药主要成分筛选与靶点获取

本 skill 封装了一套四步顺序数据处理管线，从 TCMSP 网站 (https://tcmsp-e.com) 出发，完成中药化学成分的抓取、筛选、靶点匹配、合并导出和 UniProt 基因名映射，最终产出可直接用于下游网络药理学分析（Cytoscape、STRING、KEGG 富集分析等）的完整数据集。

定位

Use when

从 TCMSP 获取中药化学成分与靶点，进行 OB≥30/DL≥0.18 筛选
需要将 TCMSP 靶点蛋白名映射到标准 UniProt ID 和 Gene Symbol
为网络药理学下游分析（交集、PPI、富集）准备药物靶点基因列表
用户提到中药成分筛选、中药靶点、TCMSP、OB/DL 筛选、UniProt 映射

Do not use when

需要收集疾病靶点基因 → 使用 Skill 2（disease-target-collection）
需要做靶点交集韦恩图 → 使用 Skill 3（target-intersection）
需要做 PPI 网络分析 → 使用 Skill 4（string-ppi-network）
需要做 GO/KEGG 富集分析 → 使用 Skill 5（enrichment-analysis）

输入输出契约

| 项目 | 内容 | |------|------| | 任务输入 | 中药名称（中文，如当归、丹参） | | 默认衔接输入 | 无上游 — 本 Skill 是采集起点，用户必须提供中药名称 | | 独立输入 | 无需上游文件；通过位置参数或 --list 提供中药名称 | | 默认输出目录 | ./np-output/tcmsp/ | | 最终产物 | Drug_Targets_Gene_List.txt — 去重基因符号列表，下游 Skill 3/4/5 直接使用 | | 可选产物 | Drug_Targets.json, Drug_Targets.csv（审计）, Drug_Targets_MatchLog.csv（人工审核） | | 下游衔接 | Skill 3（target-intersection）读取 Drug_Targets_Gene_List.txt 做交集分析 |

契约要求

Drug_Targets_Gene_List.txt 是唯一默认下游契约文件，必须生成。
自定义输出目录时，产物结构与默认一致。
UniProt TSV 缓存（np-output/cache/）与 Skill 2 共享，不重复下载。

运行模式

默认衔接模式

无需上游文件。用户提供中药名称，脚本写入 ./np-output/tcmsp/。下游 Skill 自动发现产物。

python3 $SKILL_DIR/scripts/tcmsp_fetch.py 当归
python3 $SKILL_DIR/scripts/tcmsp_filter.py
python3 $SKILL_DIR/scripts/extract_targets.py
python3 $SKILL_DIR/scripts/map_target_genes.py

独立运行模式

自定义输入输出路径，不依赖项目目录约定。支持单味药、复方列表、自定义阈值。

python3 $SKILL_DIR/scripts/tcmsp_fetch.py 黄芪 --output-dir ./my_data
python3 $SKILL_DIR/scripts/tcmsp_filter.py --input-dir ./my_data
python3 $SKILL_DIR/scripts/extract_targets.py -i ./my_data
python3 $SKILL_DIR/scripts/map_target_genes.py -i ./my_data/All_Targets.json -o ./my_data

工作流

四个步骤顺序依赖，不可跳过：

[中药名称]
  ↓ (1) tcmsp_fetch.py        → {Pinyin}_Ingredients.json + {Pinyin}_Targets.json
  ↓ (2) tcmsp_filter.py       → {Pinyin}_Ingredients_Filter.json + {Pinyin}_Targets_Filter.json
  ↓ (3) extract_targets.py    → All_Targets.json
  ↓ (4) map_target_genes.py   → Drug_Targets.json + Drug_Targets.csv + Drug_Targets_Gene_List.txt + Drug_Targets_MatchLog.csv
       (依赖 uniprot_cache.py   UniProt TSV 下载缓存，同目录独立脚本)

运行约定

始终从项目根目录运行脚本。 默认输出目录 ./np-output/tcmsp/ 解析到项目根目录下，而非 Skill 安装目录。

Skill 可能通过不同方式安装，命令模板统一使用 $SKILL_DIR 表示实际 Skill 路径：

| 安装方式 | Skill 位置 | 脚本前缀 | |----------|-----------|----------| | 项目内置 | {项目根}/tcmsp-ingredient-screening/ | tcmsp-ingredient-screening/scripts/ | | 项目级 Skill | {项目根}/.claude/skills/tcmsp-ingredient-screening/ | .claude/skills/tcmsp-ingredient-screening/scripts/ | | 全局 Skill | ~/.claude/skills/tcmsp-ingredient-screening/ | ~/.claude/skills/tcmsp-ingredient-screening/scripts/ |

跨平台命令适配

命令模板中的 python3 和 $SKILL_DIR 需要根据平台调整：

| 平台 | Python 命令 | Skill 目录变量 | 示例 | |------|-------------|---------------|------| | macOS / Linux | python3 | $SKILL_DIR (bash/zsh) | python3 $SKILL_DIR/scripts/tcmsp_fetch.py | | Windows CMD | python | %SKILL_DIR% | python %SKILL_DIR%\scripts\tcmsp_fetch.py | | Windows PowerShell | python | $env:SKILL_DIR | python $env:SKILL_DIR/scripts/tcmsp_fetch.py |

注意： Windows 通常只有 python 命令（没有 python3）。如果你的 Windows 环境安装了 python3 别名，也可以用 python3。

或者直接用绝对/相对路径替换 $SKILL_DIR：

# macOS/Linux 示例
python3 tcmsp-ingredient-screening/scripts/tcmsp_fetch.py 当归

# Windows CMD 示例
python tcmsp-ingredient-screening\scripts\tcmsp_fetch.py 当归

执行前检查

在运行任何脚本之前，必须先检查输出目录是否已存在且有内容。

这是调用者/Agent 的操作规范，不是脚本内置交互保护；脚本本身可能直接覆盖同名输出文件。

首先确定本次使用的输出目录（用户指定了 --output-dir 就用自定义目录，否则用默认的 ./np-output/tcmsp/）。然后检查该目录：

如果输出目录存在且包含结果文件，说明上次执行有残留输出。此时应提示用户：

⚠️ 检测到 {输出目录}/ 中已有上次执行的结果文件：

{列出文件}

是否删除这些文件重新开始？（UniProt 缓存在 np-output/cache/ 中不受影响）

删除并重新开始（推荐）

保留现有文件，跳过已抓取的中药

若用户选择删除：清空该输出目录
若用户选择保留：后续步骤中要检查哪些中药已有输出，避免重复抓取
若目录不存在或目录为空：直接开始执行

分步详解

Step 1: 抓取原始数据 (`scripts/tcmsp_fetch.py`)

用途： 从 TCMSP 网站抓取指定中药的全部化学成分和靶点信息。

前置条件： 网络可访问 https://tcmsp-e.com

命令模板：

| 场景 | 命令 | |------|------| | 单味药 | python3 $SKILL_DIR/scripts/tcmsp_fetch.py 当归 | | 多味药（批量） | python3 $SKILL_DIR/scripts/tcmsp_fetch.py --list 丹参,川芎,白芍 | | 自定义输出目录 | python3 $SKILL_DIR/scripts/tcmsp_fetch.py 黄芪 --output-dir ./my_data |

输出文件（位于 ./np-output/tcmsp/）：

{Pinyin}_Ingredients.json — 全部化学成分（含 OB、DL、MW 等字段）
{Pinyin}_Targets.json — 全部靶点关联（含 target_name、MOL_ID 等字段）

关键行为：

自动从 TCMSP 首页获取搜索 token
默认每次请求间隔 1.5 秒，避免被服务器限流，不要建议用户使用 --no-delay，除非用户明确要求速度优先
中药名用中文输入，脚本自动搜索并提取拼音用于文件命名

常见错误：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | 药名未找到 | ❌ 错误 | ❌ 未找到 '{name}' 的搜索结果 | 检查药名拼写；尝试英文名或拉丁名 | | 网络不通 | ❌ 错误 | ❌ 网络错误: ... | 检查网络；稍后重试 | | token 失效 | ⚠️ 警告 | ⚠️ 未找到 token | 手动用 --token 参数提供 token |

严重级别说明：⚠️ 警告 = 非致命，继续执行；❌ 错误 = 当前步骤失败，修复后可重试；💀 致命 = 需人工干预，无法自动恢复。

校验要点：

确认各中药 {Pinyin}_Ingredients.json 和 {Pinyin}_Targets.json 均已生成
检查 Ingredients 记录数是否合理（通常几十到上百条）
检查 Targets 文件非空（至少应有一些靶点记录）

Step 2: 筛选与靶点匹配 (`scripts/tcmsp_filter.py`)

用途： 按标准阈值（OB≥30 且 DL≥0.18）筛选活性化合物，并根据筛选结果的 MOL_ID 匹配对应靶点。

前置条件： Step 1 的输出文件必须存在于 np-output/tcmsp/ 中。

命令模板：

| 场景 | 命令 | |------|------| | 自动发现（推荐） | python3 $SKILL_DIR/scripts/tcmsp_filter.py | | 单味药 | python3 $SKILL_DIR/scripts/tcmsp_filter.py Danggui | | 批量指定 | python3 $SKILL_DIR/scripts/tcmsp_filter.py -l Danggui,Huangqi | | 自定义阈值 | python3 $SKILL_DIR/scripts/tcmsp_filter.py --ob 40 --dl 0.20 | | 指定目录 | python3 $SKILL_DIR/scripts/tcmsp_filter.py --input-dir ./my_data |

输出文件（位于输入目录）：

{Pinyin}_Ingredients_Filter.json — 符合阈值的化合物
{Pinyin}_Targets_Filter.json — 匹配到的靶点记录

关键行为：

无参数时自动扫描目录下所有 *_Ingredients.json（排除已有 _Filter 后缀的文件），这是最推荐的使用方式
OB 和 DL 值从字符串转为 float 进行比较，转换失败则跳过该记录
某味药缺少靶点文件时，仍输出筛选后的成分，但跳过靶点匹配

常见错误：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | 目录不存在 | ❌ 错误 | ❌ 目录不存在 | 确认 --input-dir 路径 | | 无输入文件 | ❌ 错误 | ❌ 未找到任何 *_Ingredients.json | 先运行 Step 1 | | 靶点文件缺失 | ⚠️ 警告 | ⚠️ 未找到靶点文件 | 非致命；成分筛选结果仍可用 | | 筛选后 0 条记录 | ⚠️ 警告 | 输出文件仅含 [] | 可降低 --ob 或 --dl 阈值重试 |

校验要点：

确认 {Pinyin}_Ingredients_Filter.json 记录数 > 0（否则考虑降低阈值）
确认 {Pinyin}_Targets_Filter.json 记录数合理（通常与成分数匹配）
检查是否有中药完全无靶点，如有则核实 TCMSP 数据

Step 3: 合并导出 (`scripts/extract_targets.py`)

用途： 扫描所有 *_Targets_Filter.json，提取四列核心字段（Drug、MOL_ID、Molecule_Name、Target_Name），合并输出为 JSON。

前置条件： 至少一个 *_Targets_Filter.json 存在于输入目录中。

命令模板：

| 场景 | 命令 | |------|------| | 默认 | python3 $SKILL_DIR/scripts/extract_targets.py | | 指定输入目录 | python3 $SKILL_DIR/scripts/extract_targets.py --input-dir my_data | | 简写 | python3 $SKILL_DIR/scripts/extract_targets.py -i my_data |

输出文件：

All_Targets.json — JSON 数组，供 Step 4 程序化处理

常见错误：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | 无输入文件 | ⚠️ 警告 | [警告] 未找到任何 *_Targets_Filter.json | 先运行 Step 2 |

校验要点：

确认 All_Targets.json 为非空 JSON 数组
检查每条记录包含四列核心字段（Drug, MOL_ID, Molecule_Name, Target_Name）
记录数应与各味药 _Targets_Filter.json 总和一致

Step 4: UniProt 基因名映射 (`scripts/map_target_genes.py`)

用途： 将 All_Targets.json 中的 Target_Name（蛋白名称）映射到标准的 UniProt ID 和 Gene Symbol，为后续网络药理学分析提供标准化的基因标识。

前置条件： All_Targets.json 必须存在于 np-output/tcmsp/ 中。

命令模板：

| 场景 | 命令 | |------|------| | 默认 | python3 $SKILL_DIR/scripts/map_target_genes.py | | 强制重下载蛋白组数据 | python3 $SKILL_DIR/scripts/map_target_genes.py --force-download | | 自定义路径 | python3 $SKILL_DIR/scripts/map_target_genes.py -i my_data/All_Targets.json -o my_data | | 自定义别名文件 | python3 $SKILL_DIR/scripts/map_target_genes.py --aliases my_aliases.csv | | 单独管理 TSV 缓存 | python3 $SKILL_DIR/scripts/uniprot_cache.py | | 强制刷新 TSV 缓存 | python3 $SKILL_DIR/scripts/uniprot_cache.py --force |

四层匹配策略（按优先级从高到低）：

| 层级 | 匹配方式 | 标记 | |------|----------|------| | L1 | 精确匹配：Target_Name 直接等于 TSV 中的 protein_name（大小写不敏感） | exact_match | | L2 | 归一化匹配：去标点、连字符、大小写、希腊字母后与完整 protein_name 比较 | normalized_match | | L3 | 结构化拆解匹配：将 protein_name 拆为推荐名/别名/剪切片段，归一化后匹配 | structural_match | | L4 | 别名表：从外部 CSV 文件（np-output/cache/target_aliases.csv）加载的人工映射兜底 | alias_match | | — | 四层均失败 | not_found |

输出文件：

Drug_Targets.json — 原数据 + UniProt_IDs + Gene_Names + Match_Status
Drug_Targets.csv — 同上，CSV 格式（Excel 友好，UTF-8 BOM 编码）
Drug_Targets_Gene_List.txt — 去重基因符号列表（一行一个），下游 Skill 3/4/5 直接使用
Drug_Targets_MatchLog.csv — 非精确匹配（L2/L3/L4/NOT_FOUND）的审计日志，格式对齐别名表，可直接追加复用

关键行为：

TSV 下载缓存逻辑已独立到同目录的 uniprot_cache.py，可单独运行管理缓存
首次运行自动从 UniProt 下载人类蛋白组 TSV（Swiss-Prot reviewed + Homo sapiens），缓存于 np-output/cache/uniprot_proteome.tsv
当天内重复运行使用缓存；跨天或文件过小则自动重下载
该缓存与 disease-target-collection Skill 共享，无需重复下载
构建多层索引（raw_lower / norm / primary / alts / subs），L3 结构化拆解覆盖 UniProt protein_name 的推荐名、括号别名、逗号切分片段、[Cleaved into:/Includes:] 子项
别名表从 np-output/cache/target_aliases.csv 加载（CSV 格式，可用 Excel/Numbers 编辑）
自动生成别名模板（脚本副作用，非决策门 A 分支）： 发现 NOT_FOUND 靶点时，脚本将其追加到 target_aliases.csv 作为待填充模板行（UniProt_ID 和 Gene_Name 留空）。这只是为可能的 A 分支预留模板，不代表已进入 A 分支；是否由技能填入建议映射并运行 validate_aliases.py，取决于用户在「NOT_FOUND 决策门（权威说明）」处的选择
运行结束后打印匹配汇总（四层各自数量和总体匹配率）
列出所有 NOT_FOUND 靶点及追加到别名表的数量
列出所有 L3 结构化匹配靶点，提醒人工确认
可通过 --aliases 指定自定义别名文件路径

常见错误：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | API 限流 | ❌ 错误 | ❌ HTTP 错误: 429 | 脚本自动等待 Retry-After 后重试（最多 3 次） | | TSV 下载失败 | ❌ 错误 | ❌ TSV 下载失败 | 网络恢复后重试，或手动 --force-download | | 出现 not_found | ⚠️ 警告 | 输出中出现任意 → (not found)（哪怕一条） | 触发 NOT_FOUND 决策门（强制停止点）：停止执行、交还控制权、等待用户在 (A)/(B) 间的明确答复后才能继续。详见下方「NOT_FOUND 决策门」权威说明 | | 大量 structural_match | ⚠️ 警告 | L3 拆解命中数量偏高 | 人工审核脚本输出的 L3 靶点列表，确认无误即可 |

校验要点：

确认 Drug_Targets_Gene_List.txt 已生成且非空（最终契约产物）
检查匹配率汇总（四层各自数量），总体匹配率应 > 80%
只要 Match_Status 出现任意 not_found，触发 NOT_FOUND 决策门（强制停止点，详见下方「NOT_FOUND 决策门」权威说明）：停止执行、交还控制权、呈现清单与 A/B 选项，收到用户明确答复后才能继续

NOT_FOUND 决策门（权威说明）

这是本 Skill 唯一权威的决策门定义。SKILL.md 其余位置（Step 4 错误表、校验要点、错误处理指南、执行检查清单）均只是引用此处，不重复定义。出现冲突时以本节为准。

触发条件（无模糊地带）： Step 4 输出的 Match_Status 中出现任意一条 not_found——哪怕只有 1 条——即触发。不存在"数量太少不算"的例外。

这是一个强制停止点，与工具无关的行为契约（任何 harness 都必须满足）：

停止执行。 不得运行任何后续脚本，不得推进到下游 Skill（Skill 2+）。即便在多 Skill 串联的全流程中，也不得携带 NOT_FOUND 缺口自动前进。
交还控制权给用户。 结束当前回合，呈现 NOT_FOUND 清单 + A/B 选项。
必须收到用户对 A 或 B 的明确答复后，才能继续。 在此之前的任何自动推进都属于违反流程。
工具落地（按 harness 能力分级）：
- 若当前 harness 提供结构化提问 / 审批工具（如 Claude Code 的 AskUserQuestion），必须优先使用，以获得明确的阻塞式选择框；
- 若没有此类工具（如部分 Codex / 其他框架），则以"输出 A/B 选项后结束本回合、停止调用任何工具、等待用户下一条输入"的方式实现等待。
- 无论哪种方式，第 1–3 条的硬约束都不变。

呈现给用户的内容（先分类，再给选项）：

先把 NOT_FOUND 靶点初步分成两类，让用户的 A/B 选择有依据：

疑似非人类 / TCMSP 噪音（细菌、植物、大鼠等非人类蛋白，mRNA 等）——大概率不应进入人类网络药理学基因列表；
疑似真人类靶点漏映射——值得走 A 分支补齐，否则会丢失有效靶点。

然后呈现二选一：

(A) 补充后重跑（用户选择 A 之后才执行以下步骤，均非默认自动链）：
1. 技能将每个疑似人类靶点的建议 UniProt_ID / Gene_Name 填入 np-output/cache/target_aliases.csv 的待填充模板行（脚本首次运行已自动追加这些模板行），优先 Swiss-Prot (Reviewed) + Homo sapiens；明显非人类条目保持留空跳过。
2. 运行 validate_aliases.py 用 UniProt 人类 TSV 校验（PASS / WARN / FAIL / PENDING）。
3. 将填入清单 + 校验汇总呈现给用户，再次询问是否需要人工核查；用户采纳建议或完成核查后，重新运行 Step 4。
(B) 忽略并继续： 保留当前匹配结果，NOT_FOUND 靶点不进入基因列表，直接进入下游 Skill。

别名 CSV 文件维护

target_aliases.csv 位于 np-output/cache/target_aliases.csv，是 L4 别名匹配（兜底）的数据源。用户无需懂 Python 即可编辑：

CSV 格式：

| 列名 | 必填 | 说明 | |------|------|------| | Target_Name | ✅ | TCMSP 中的靶点蛋白名称（需与脚本输出的 NOT_FOUND 靶点名完全一致） | | UniProt_ID | ✅ | UniProt accession ID（如 P17612） | | Gene_Name | ✅ | 标准基因符号（如 PRKACA） | | Notes | ❌ | 备注，可选（如 "Pseudomonas putida, 非人类"） |

决策门 A 分支的补充工作流：

⚠️ 以下步骤 2–5 只在用户已在 NOT_FOUND 决策门选择 (A) 之后才执行，不是首次运行就跑的自动链。步骤 1（模板行追加）是脚本副作用，与决策门无关，先于决策发生。

首次运行 Step 4 的脚本副作用：脚本执行四层匹配（L1-L4），并在发现 NOT_FOUND 靶点后将其追加到 target_aliases.csv 作为待填充模板行（Target_Name 已填充，UniProt_ID / Gene_Name 留空，Notes 提示待补充）。这只是为 A 分支预留模板，不代表已进入 A 分支——是否补齐仍取决于用户在决策门的选择。
（用户选 A 后）填入建议映射：技能（基于基因命名法背景知识）将每个疑似人类靶点的建议 UniProt_ID 和 Gene_Name 写入对应模板行，优先 Swiss-Prot (Reviewed) + Homo sapiens 条目；明显的非人类条目（细菌/植物/大鼠蛋白、mRNA 等 TCMSP 噪音）保持留空跳过。
（用户选 A 后）验证映射：运行 validate_aliases.py，用 UniProt 人类蛋白组 TSV 缓存校验每一行刚填入的 (UniProt_ID, Gene_Name)：
```
python3 $SKILL_DIR/scripts/validate_aliases.py
python3 $SKILL_DIR/scripts/validate_aliases.py --fail-only   # 只看需处理的行
```
三档结果：
- ✅ PASS — accession 存在于人类 TSV 且其 primary gene 与填入的 Gene_Name 自洽，可直接采用
- ⚠️ WARN — 部分命中（accession 与基因名对不上，或一方不在 TSV），需人工再确认
- ❌ FAIL — accession 和基因名都不在人类 reviewed TSV，多为非人类条目或幻觉，应留空/删除
- ⬜ PENDING — 仍为空（待填充或有意跳过的噪音条目）
⚠️ 注意： TSV 验证只保证"是真实人类蛋白且 ID/基因名自洽"，不能判断该映射在语义上是否对应原始靶点名（例如把 Thrombin 错配到另一真实蛋白仍会 PASS）。因此 PASS 不等于免审核。退出码：有 FAIL 时为 1，否则为 0。
（用户选 A 后）呈现结果并再次询问是否人工核查：技能将 PASS/WARN/FAIL/PENDING 汇总和已填入的映射清单呈现给用户，然后询问用户是否需要人工核查：
- 用户选择人工核查 → 用户复核 WARN 行、确认 PASS 的语义正确性、按需修改 target_aliases.csv，确认后继续
- 用户选择采纳建议 → 直接采用技能填入的映射
重新运行 Step 4，脚本自动读取补充后的别名，完成 L4 匹配

手动补充（备用方法）：

如果需要手动编辑 Drug_Targets_MatchLog.csv 后追加到别名表：

编辑 Drug_Targets_MatchLog.csv，补充 NOT_FOUND 行的 UniProt_IDs 和 Gene_Names 列
将确认无误的行手动追加到 target_aliases.csv（仅需前 4 列：Target_Name, UniProt_ID, Gene_Name, Notes）
重新运行 Step 4

💡 提示： 用 Excel 编辑时直接保存即可（脚本自动处理 BOM）。用文本编辑器时确保保存为 UTF-8 编码。

完整运行示例

场景 A：单味药研究（如当归）

python3 $SKILL_DIR/scripts/tcmsp_fetch.py 当归
python3 $SKILL_DIR/scripts/tcmsp_filter.py
python3 $SKILL_DIR/scripts/extract_targets.py
python3 $SKILL_DIR/scripts/map_target_genes.py

场景 B：复方研究（如丹参+川芎+白芍）

python3 $SKILL_DIR/scripts/tcmsp_fetch.py --list 丹参,川芎,白芍
python3 $SKILL_DIR/scripts/tcmsp_filter.py
python3 $SKILL_DIR/scripts/extract_targets.py
python3 $SKILL_DIR/scripts/map_target_genes.py

提示： Step 2 使用自动发现模式（无参数）最省事，自动处理目录下所有已抓取的中药。

提示： 以上示例假设 $SKILL_DIR 已替换为实际的 Skill 安装路径（如 .claude/skills/tcmsp-ingredient-screening）。

错误处理与恢复指南

执行过程中遇到错误时，按以下策略处理：

| 状况 | 严重级别 | 诊断信号 | 恢复操作 | |------|----------|----------|----------| | Step 1 药名未找到 | ❌ 错误 | ❌ 未找到 '{name}' 的搜索结果 | 确认药名拼写正确；尝试英文名；手动访问 TCMSP 网站验证 | | Step 1 网络错误 | ❌ 错误 | ❌ 网络错误 或超时 | 重试；检查网络；TCMSP 网站可能临时不可用 | | Step 1 token 失效 | ⚠️ 警告 | ⚠️ 未找到 token | 告知用户 TCMSP 页面可能已更新，需手动从浏览器获取 token | | Step 2 无输入文件 | ❌ 错误 | ❌ 未找到任何 *_Ingredients.json | 确认已运行 Step 1；检查输出目录 | | Step 2 靶点文件缺失 | ⚠️ 警告 | ⚠️ 未找到靶点文件 | 非致命错误；筛选后的成分已保存，靶点匹配被跳过 | | Step 2 筛选结果为零 | ⚠️ 警告 | 输出文件仅含 [] | 降低 OB/DL 阈值重试，如 --ob 20 --dl 0.10 | | Step 3 无输入文件 | ❌ 错误 | [警告] 未找到任何 *_Targets_Filter.json | 确认已运行 Step 2 | | Step 4 下载失败 | ❌ 错误 | ❌ HTTP 错误: 429 | 脚本内置重试；或等待后 --force-download | | Step 4 出现 NOT_FOUND（哪怕一条） | ⚠️ 警告 | 输出中出现任意 → (not found) | 触发 NOT_FOUND 决策门（强制停止点）：停止执行、交还控制权、等待用户在 (A)/(B) 间明确答复后才能继续。具体行为契约与 A/B 步骤见上方「NOT_FOUND 决策门（权威说明）」，此处不重复定义 | | 自定义输出目录不一致 | ❌ 错误 | Step N 找不到文件 | 确保所有步骤使用相同的目录参数 |

资源组织

scripts/ — 确定性脚本和可重复执行的处理流程：tcmsp_fetch.py（抓取）、tcmsp_filter.py（筛选）、extract_targets.py（合并）、map_target_genes.py（映射）、validate_aliases.py（别名表 TSV 校验）、uniprot_cache.py（TSV 缓存管理）
references/ — 暂无（参数表、API 细节、长错误表保留在本 SKILL.md 中）
assets/ — 暂无（本 Skill 无模板或静态资源）

执行检查清单

[ ] 检查残留文件 — 若 np-output/tcmsp/ 存在且有内容，提示用户是否清空后重新开始
[ ] 确认中药名称 — 与用户确认要研究的中药名称（中文）
[ ] 确认参数 — 是否需要自定义 OB/DL 阈值？是否需要自定义输出目录？
[ ] Step 1: 抓取 — 运行 $SKILL_DIR/scripts/tcmsp_fetch.py，确认输出文件生成
[ ] Step 2: 筛选 — 运行 $SKILL_DIR/scripts/tcmsp_filter.py（推荐自动发现模式），检查筛选结果数量是否合理
[ ] Step 3: 合并 — 运行 $SKILL_DIR/scripts/extract_targets.py，确认 All_Targets.json 生成
[ ] Step 4: 映射 — 运行 $SKILL_DIR/scripts/map_target_genes.py，展示匹配率汇总给用户
[ ] NOT_FOUND 决策门（关键，强制停止点） — 只要 Step 4 的 Match_Status 出现任意一条 not_found（哪怕 1 条）即触发。此时停止执行、交还控制权、等待用户在 (A)/(B) 间明确答复后才能继续——完整定义见上文「NOT_FOUND 决策门（权威说明）」，此处不重述。
- 工具落地：harness 有结构化提问工具（如 Claude Code 的 AskUserQuestion）时必须优先使用；没有则输出 A/B 后结束本回合等待用户输入。
- (A) 补充后重跑 / (B) 忽略并继续 的具体步骤以权威说明为准。
- 全流程（多 Skill 串联）同样适用：不得在未经用户确认的情况下携带 NOT_FOUND 缺口自动推进到 Skill 2+。
[ ] 人工审核 — 提醒用户查看 Drug_Targets_MatchLog.csv，确认 NOT_FOUND 和 L3 structural_match 条目

注意事项

请求限速：Step 1 默认 1.5 秒延迟，不要建议用户使用 --no-delay，除非用户明确要求速度优先并接受被限流风险
输出目录位置：始终从项目根目录运行，默认输出 ./np-output/tcmsp/ 解析到项目根目录下（而非 Skill 安装目录内）。所有步骤共享同一输出目录，保持一致性
输出目录一致性：如果 Step 1 用了 --output-dir 自定义目录，后续步骤需同步指定同一目录（--input-dir / --output-dir）
幂等性：Step 2/3/4 可重复运行（覆盖输出），Step 1 也可重复运行但会浪费网络请求，建议先检查输出文件是否已存在
人工审核环节：Step 4 的 Drug_Targets_MatchLog.csv 记录了所有非精确匹配的靶点（L2/L3/L4/NOT_FOUND），用户应在下游分析前审核。NOT_FOUND 条目的处理一律遵循上文「NOT_FOUND 决策门（权威说明）」——这是强制停止点，须先停下、交还控制权、等用户在 A/B 间明确选择后才继续，本节不重复定义其流程。L3 structural_match 条目也需要人工确认是否准确。Drug_Targets_MatchLog.csv 格式对齐别名表，可将确认无误的行直接追加到别名 CSV 中。
下游分析衔接：输出的 Drug_Targets.json、Drug_Targets.csv 和 Drug_Targets_Gene_List.txt 可直接用于 Cytoscape 构建网络、STRING PPI 分析、DAVID/KEGG 通路富集分析等

tcmsp-ingredient-screening

中药主要成分筛选与靶点获取

定位

输入输出契约

运行模式

默认衔接模式

独立运行模式

工作流

运行约定

跨平台命令适配

执行前检查

分步详解

Step 1: 抓取原始数据 (scripts/tcmsp_fetch.py)

Step 2: 筛选与靶点匹配 (scripts/tcmsp_filter.py)

Step 3: 合并导出 (scripts/extract_targets.py)

Step 4: UniProt 基因名映射 (scripts/map_target_genes.py)

NOT_FOUND 决策门（权威说明）

别名 CSV 文件维护

完整运行示例

场景 A：单味药研究（如当归）

场景 B：复方研究（如丹参+川芎+白芍）

错误处理与恢复指南

资源组织

执行检查清单

注意事项

Step 1: 抓取原始数据 (`scripts/tcmsp_fetch.py`)

Step 2: 筛选与靶点匹配 (`scripts/tcmsp_filter.py`)

Step 3: 合并导出 (`scripts/extract_targets.py`)

Step 4: UniProt 基因名映射 (`scripts/map_target_genes.py`)