> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/getting-started/metabolic-dark-matter.md).

# 用 Duaer 注释未知特征（代谢暗物质）

在 Duaer 里逐步处理谱库认不出的质谱特征：谱库匹配、质量候选、参考谱图与 MASST，每步一次 Duaer Data 调用。
## 什么是代谢暗物质

在 Duaer 里，代谢暗物质指谱库认不出的质谱特征：有 m/z 或 MS/MS 谱图，却没有鉴定结果。

Duaer 不用一个大工具包办，而是把几项单一功能的 Duaer Data 串起来：每步一次调用，看结果再决定下一步。

## 步骤

1. 有 USI 时，先用 [USI 取谱](/zh/getting-started/spectrum.md) 拿到峰列表和前体 m/z。
2. 用 [MassBank 谱图](/zh/getting-started/massbank.md) 按峰匹配谱库；score ≥ 0.8 且前体一致，多半已鉴定，可跳到最后一步。
3. 没匹配上时，用 [质量候选物](/zh/getting-started/mass-candidates.md) 按前体 m/z、加合离子和 ppm 列出 PubChem 候选。
4. 对排前面的候选，用 [MoNA 谱图](/zh/getting-started/mona.md)（或 MassBank 的 InChIKey）取参考谱图，比对主要碎片。
5. 用 [MASST](/zh/getting-started/masst.md) 查这张谱图出现在哪些公开数据集；多项研究都出现，更可能是真实代谢物。
6. 对已鉴定或疑似化合物，用 [RefMet](/zh/getting-started/refmet.md)、[KEGG](/zh/getting-started/kegg.md) 或 [Rhea](/zh/getting-started/rhea.md) 补通路与反应。

只有 m/z（MS1）时，跳过取谱、谱库匹配和 MASST。一个特征通常 3 到 8 次调用。

## 结果怎么报

- 结果：化合物名称与 InChIKey，或「未知」。
- 每步证据：调用、首位结果、score / ppm 误差 / 数据集数。
- 置信：谱库匹配为「已鉴定」，有共有碎片的候选为「疑似」，仅质量吻合为「仅质量」。

只凭质量不能定结构：葡萄糖、半乳糖、果糖分子式相同。

## 技能（英文）

把这段技能交给智能体，它会按步骤调用 Duaer Data。

```
---
name: duaer-metabolic-dark-matter
description: >-
  Work an unannotated metabolomics feature (an m/z or MS/MS spectrum that no library identified)
  step by step with Duaer Data. Each step is one Duaer Data call that uses 1 Duaer credit.
---

# Duaer: annotate an unknown feature (metabolic dark matter)

Metabolic dark matter is the MS features that no library identifies. This Duaer skill chains single-purpose Duaer Data calls.
Run one step, read its result, then decide the next step. Report what each call returned.

## Input

One of:

- A USI (`mzspec:...`) of a public spectrum.
- MS/MS peaks (`mz:intensity` pairs) with the precursor m/z, an adduct guess, and the ion mode.
- Only an m/z (MS1 feature) with an adduct guess. Skip steps 1, 2, and 5.

## Steps

1. **Get peaks.** For a USI, call https://skills.duaer.com/spectrum.md. Keep `peaks` and `precursorMz`.
2. **Library match.** Call https://skills.duaer.com/massbank.md with `peaks` and `ionMode`.
   A `score` of 0.8 or more with a matching precursor is a likely identification. If you have one, go to step 6.
3. **Mass candidates.** Call https://skills.duaer.com/mass-candidates.md with the precursor m/z, the adduct, and `ppm` (5 for high-resolution data).
4. **Compare candidates.** For the top candidates, call https://skills.duaer.com/mona.md with each `inchikey`
   (or https://skills.duaer.com/massbank.md with `inchikey`). Compare reference `peaks` and `precursorType` with yours.
   Shared major fragments support a candidate. No shared fragments rules it out.
5. **Where it occurs.** Call https://skills.duaer.com/masst.md with the USI or the peaks.
   `library=public` lists public datasets that contain the same spectrum. `library=gnpsLibrary` finds GNPS reference spectra.
   A spectrum seen across several studies or sample types is more likely a real metabolite than noise.
6. **Context.** For an identified or putative compound, use https://skills.duaer.com/refmet.md for the standard name and class,
   and https://skills.duaer.com/kegg.md or https://skills.duaer.com/rhea.md for pathways and reactions.

## Report

For each feature return:

- Input (USI, precursor m/z, adduct, ion mode).
- Result: the compound name and InChIKey, or `unknown`.
- Evidence per step: the call, the top hit, and its score, ppm error, or dataset count.
- Confidence: `identified` (library spectrum match), `putative` (candidate with shared fragments), `mass only`, or `unknown`.
- A next step, such as running an authentic standard.

## Rules

- Mass alone never identifies a compound. Isomers share a formula (glucose, galactose, fructose).
- Cite only returned results. Do not invent names, InChIKeys, scores, or datasets.
- One Duaer Data call per step. A feature usually takes 3 to 8 calls.

## Keys

Header: `Authorization: Bearer <Duaer key>`

Use an account key or a model API key.

Get a Duaer key: https://skills.duaer.com/keys.md

## Credits

Each successful Duaer Data call uses 1 credit, including a call that finds no match.
Empty input, a failed source, or no remaining credits uses 0.

```
## Questions

### Duaer 注释一个未知特征要多少额度？

每次 Duaer Data 调用成功扣 1 额度，一个特征通常 3 到 8 次。

### Duaer 能直接给出未知物结构吗？

不能保证。Duaer 给出谱库匹配、候选和出现位置等证据，并标明置信等级；定结构仍需标准品验证。

## 相关

- [在 Duaer 里按 USI 取谱](https://doc.duaer.com/zh/getting-started/spectrum.md)
- [在 Duaer 里匹配 MassBank 谱图](https://doc.duaer.com/zh/getting-started/massbank.md)
- [在 Duaer 里列出质量候选物](https://doc.duaer.com/zh/getting-started/mass-candidates.md)
- [在 Duaer 里查 MoNA 参考谱图](https://doc.duaer.com/zh/getting-started/mona.md)
- [在 Duaer 里用 MASST 搜谱图](https://doc.duaer.com/zh/getting-started/masst.md)
- [在 Duaer 里检索 RefMet](https://doc.duaer.com/zh/getting-started/refmet.md)