primer-design

引物设计与特异性

以 5' 端到 3' 端方向生成候选寡核苷酸，并为每个结论附上确切的模板、化学体系、预期产物和搜索范围。使用提供的工具计算序列相关量。熟悉的基因名称、良好的 Primer3 罚分或单一 BLAST 比对都无法确立引物特异性。

选择工作流

需求	从这里开始
新的基因组 PCR 或 RT-qPCR 引物对	定义检测和参考序列；设计；评估热力学；筛查产物。
检查现有引物对	准备引物对 TSV；评估完整寡核苷酸和退火核心；使用明确的预期坐标进行筛查。
外显子连接、转录本异构体、等位基因区分	阅读 design-workflows.md；在施加约束前提供序列注释。
克隆/带接头尾的引物	设计退火核心，附加声明的 5' 端尾，重新评估完整寡核苷酸，重建最终产物。
多重检测组合	在热力学和特异性工具中均启用 --multiplex，以评估寡核苷酸相互作用和跨引物对产物。
简并、亚硫酸氢盐、探针或修饰碱基检测	使用 design-workflows.md 中的专用工作流；捆绑的普通 DNA 模型不充分。

本地工具支持具有明确 ACGT 核心的成对引物。高级检测类型有实质性的设计和验证指导，但不会在未说明的情况下被简化为普通 PCR。本技能设计检测；表达归一化、实验诊断验证和引导 RNA 设计是独立的任务。

确立检测契约

获取会改变结果的信息；对于探索性设计，使用明确的临时假设，并在报告中标明：

• 目的和模板： 基因组 DNA、cDNA、质粒或其他确定的底物；目标生物、登录号含版本、组装/转录本版本、链、所需异构体和产物大小范围。列出所需和不需要的模板。
• 序列证据： 本地 FASTA 加上来源/检索日期及其 SHA-256 哈希值。位点摘录使用本地坐标；记录其到完整参考序列的映射。在适当的筛查中包含相关的旁系同源基因、假基因、替代重叠群、转录本异构体、载体骨架和宿主序列。
• 反应条件： 聚合酶/缓冲液、单价盐、总二价盐、总 dNTP 和寡核苷酸浓度。Primer3 使用 mM 表示盐/dNTP，使用 nM 表示 DNA。将初始反应浓度与 Primer3 的有效退火寡核苷酸浓度参数分开记录。引擎默认值是假设。
• 约束： 目标区间、允许/排除的结合区域、连接点、变异排除及其来源、固定引物、尾或多重检测成员资格。不要猜测外显子边界或未说明地替换为其他组装。
• 可接受结果的定义： 相关的脱靶参考序列、扩增子长度、错配搜索限制、对照和适合该检测的实验验证。不存在能验证所有 PCR 的通用热力学截断值。

使用 input-contract.md 了解文件模式和坐标示例。将 assay-report-template.md 复制到分析目录中以收集证据。参考序列检索可以手动进行，也可以通过已建立的序列 API 进行；保留登录号/版本并验证返回的序列。提供的脚本使用本地文件，不会将序列在线提交。

安装与验证

将 SKILL_DIR 设置为该技能实际安装的目录。请在一个单独的分析目录中工作，以免环境、参考数据库和结果进入该技能目录。

uv venv --python 3.13 .venv-primer
uv pip install --python .venv-primer/bin/python -r "$SKILL_DIR/assets/requirements.txt"
.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" --help

在 Windows 上使用环境中的 Scripts/python.exe。设计/热力学示例针对 primer3-py 2.3.1，已在 Python 3.13 上测试。对于可选的 BLAST 引擎，请从其官方发行版安装 NCBI BLAST+ 并检查：

blastn -version
makeblastdb -version

本地集成检查也会运行 BLAST+ 2.17.0；其他版本在声称具有同等覆盖范围之前，需要检查其输出和搜索行为。

在更新依赖或 API 假设时，请阅读 sources.md。脚本会在其 JSON 报告中记录引擎版本和实际生效的设置。

1. 设计候选

对于初步功能演示，请使用随附的合成序列。它是非生物学的示例输入，不是经过实验验证的检测：

.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" \
  --template "$SKILL_DIR/assets/demo-template.fasta" \
  --preset qpcr --config "$SKILL_DIR/assets/qpcr-config.json" \
  --output design.json --pairs-out pairs.tsv --expected-out expected.tsv

对于实际工作，请替换为经过审核的目标 FASTA 和约束条件。多记录 FASTA 需要 --record 及其精确 ID。pcr 预设请求 100–1000 bp；qpcr 请求 70–200 bp。可在配置中覆盖这些起始范围。示例将其范围覆盖为 90–180 bp，并包含一个特定的目标区间。多个 SEQUENCE_TARGET 区间是备选关系：Primer3 会侧翼扩增其中至少一个。若要求覆盖每个区间，请提供一个包含全部区间的目标并验证返回的产物；不同的检测需要分别进行设计运行。

该工具：

• 将经过验证的 sequence_args 和 global_args 传递给 Primer3。不受支持或拼写错误的标签会导致失败，而不会静默改变任务。
• 将模糊的模板位置转换为 N，并禁止模糊的引物碱基。它不会将小写序列解释为重复序列掩码；请使用显式排除项。
• 可选导入 --mask-bed 排除项，采用所提供模板的坐标。仅在验证参考映射之后，才使用 BED 区间进行变异/重复序列掩码；它不会推断等位基因频率或转换任意 VCF。
• 将返回的正向和反向序列与模板进行核对，并检查产物长度。Primer3 的右引物位置会转换为半开结合区间；反向引物已处于排序方向。
• 可选将 --forward-tail 和 --reverse-tail 追加到核心序列。设计评分和核心 Tm 不包含这些尾部；第 2 步会检查完整的寡核苷酸。

当未找到候选时，请检查 engine_explanations。更改有生物学依据的约束并重新运行；不要静默放宽所有约束或返回凭空编造的序列。在比较参数选择时，请保留先前的报告。

expected.tsv 描述的是在设计模板上的预期产物。若在另一个参考序列上筛选，请将这些坐标映射到其精确的记录 ID 和方向。cDNA 产物不能跨内含子重新标记为基因组区间。

2. 评估热力学

使用与设计相同的化学环境。以下显式取值与捆绑设计的默认值一致；当实际条件不同时，请一并替换它们：

.venv-primer/bin/python "$SKILL_DIR/scripts/check_thermodynamics.py" \
  --pairs pairs.tsv --mv-conc 50 --dv-conc 1.5 --dntp-conc 0.6 \
  --dna-conc 50 --temp-c 37 --output thermodynamics.json

报告中包含核心 Tm、核心及全长寡核苷酸的发夹/同源二聚体、全长寡核苷酸异源二聚体、自身 3 端稳定性，以及两个方向的寡核苷酸间 3 端稳定性计算。Delta-G 和 delta-H 以 kcal/mol 为单位报告；delta-S 以 cal/(mol K) 为单位。--temp-c 控制 delta-G 的温度，并非推荐的 PCR 退火温度。

如果设计使用了不同的 Tm/盐模型，还需设置 --tm-method 和 --salt-corrections-method 以匹配；参见输入契约中的映射。

对于 panel，添加 --multiplex 以检查所有无序寡核苷酸组合，包括不同配对之间的正向/正向和反向/反向组合。请区分待组合的 panel 与将单独测试的备选候选。

在解读这些取值之前，请阅读 thermodynamics.md。超过 60 个碱基的全长寡核苷酸报告为未解析；它们绝不会被静默截断。修饰碱基和简并混合物需要合适的模型。热力学预测支持排序和实验规划，而非对引物质量的一概断言。 非有限 Tm 或等于/低于绝对零度的 Tm 会被视为计算/输入失败而拒绝；此类结果不得作为普通低 Tm 引物参与排序。

3. 筛查扩增产物

在做出特异性断言之前，请阅读 specificity.md。 在两条链上搜索每条引物，并配对朝内的结合位点。仅有结合命中并不构成扩增子；未报告命中并不证明不存在。

穷举式有界局部搜索

.venv-primer/bin/python "$SKILL_DIR/scripts/screen_specificity.py" \
  --pairs pairs.tsv --reference "$SKILL_DIR/assets/demo-template.fasta" \
  --expected expected.tsv --engine exhaustive \
  --min-product 40 --max-product 1000 --max-mismatches 2 \
  --three-prime-bases 5 --max-three-prime-mismatches 0 \
  --output specificity.json

这会在有界局部参考序列中枚举全长、无空位的结合位点，并检查每一对的 F/R、R/F、F/F 和 R/R 产物。参考序列的模糊性被保守地视为未解析序列；它无法确立干净的结果。错配限制是一种搜索模型，而非经过验证的聚合酶区分规则。严格的 3 端阈值可能排除可扩增的错配位点；在评估该不确定性时应放宽搜索。

对环状分子使用 --circular RECORD_ID。环绕产物使用规范起始坐标和大于参考序列长度的未环绕末端；仅考虑至多跨越一个分子的产物。对比较、命中和产物的上限可防止无界工作；触及上限会使结果不完整。

BLAST 辅助的局部搜索

.venv-primer/bin/python "$SKILL_DIR/scripts/screen_specificity.py" \
  --pairs pairs.tsv --reference "$SKILL_DIR/assets/demo-template.fasta" \
  --expected expected.tsv --engine blast \
  --min-product 40 --max-product 1000 --max-mismatches 2 \
  --three-prime-bases 5 --max-three-prime-mismatches 0 \
  --output specificity-blast.json

该脚本构建临时本地 BLAST 数据库，运行短查询比对，重新检查完整的引物长度候选位点，并记录命令和版本。它会检查配置的命中上限和工具故障。BLAST 发现是启发式的：成功执行且上限未饱和并不确立穷举覆盖。参考序列被加载到内存中；对于大型基因组，请规划内存和搜索边界。小示例验证的是执行，而非人类基因组的灵敏度或可扩展性。

对于更广泛的公共参考序列筛查，请遵循 specificity.md 中官方的 NCBI Primer-BLAST 工作流，审慎选择生物体、数据库、目标模板、最大产物长度和错配策略。提交序列会将其发送至 NCBI；仅限本地的工作应保持在本地。Primer-BLAST 并非这些脚本所实现的文档化 REST API。

解读结果

• potential_off_target：检查每一个非预期产物，包括其方向、长度、错配位置和参考序列身份；重新设计或论证其相关性。
• intended_target_not_found：在得出特异性结论之前，先解决比对、参考、序列和搜索问题。
• no_expected_target：结果只是一份产物清单，没有针对特定目标的结论。请提供该检测的所有预期产物区间。
• incomplete：参考序列不确定、资源限制或计算失败导致结论无法确定。查看报告的原因并适当重复。
• no_off_target_found_within_search_scope：说明确切的参考序列和搜索模型。检查报告中的详尽/启发式标志；这并非实证验证。

对于多重反应，在特异性命令和热力学命令中都加上 --multiplex。特异性工具随后会搜索所有跨对寡核苷酸组合，并保留原始寡核苷酸身份和尾部。它将跨对产物视为非预期产物；有意共用引物的设计需要以显式独立组合形式提供，并附上经过审核的预期产物。--max-panel-combinations 上限默认为 10,000，并在扩展前进行检查。热力学 --multiplex 检查结构；特异性 --multiplex 检查参考产物。二者对于此 panel 评估都是必需的。

4. 验证检测并交付证据

根据检测目的、覆盖度、特异性证据和化学体系选择候选方案，而不仅仅是最低的 Primer3 罚分。当仍存在不确定性时，保留多个候选方案。按照 design-workflows.md 进行相关实验检查：预期产物身份/大小、阴性和无模板对照、RT-qPCR 的基因组污染对照，以及预期用于定量时的效率/动态范围评估。仅凭单一熔解峰并不能证明身份。

交付填写完成的报告模板、配对 TSV、设计/热力学/特异性 JSON 和源清单。包括：

1. 确切的订购序列、分离的退火核心和尾部、引物长度、预期产物坐标/大小，以及任何相关的转录本/剪接点映射。
2. 化学体系和模型设置；引擎版本；参考序列登录号/版本、来源、检索日期和文件哈希；明确排除项及理由。
3. 预期产物和潜在非预期产物；来自未知碱基、不完整参考序列、启发式搜索、上限和不支持的检测化学体系的不确定性。
4. 实际获得的实验证据、尚未完成的验证，以及每个推荐候选方案的理由。准确标注未经测试的候选方案。

本实现的验证与局限

tests/primer-design/ 中的仓库测试套件会实际运行 Primer3 计算、方向与坐标重建、掩蔽、尾部、浓度处理、脱靶产物几何、错配/简并行为、失败状态，以及在安装了其可执行文件时的本地 BLAST 集成。合成夹具确立的是软件行为；它们并不验证生物检测，也不能证明全基因组召回。

工具在计算完成时返回 0，在完成设计但没有候选方案或长寡核苷酸热力学不完整时返回 1，在输入无效或工具失败时返回 2。即使在退出码为 0 后，也要阅读 JSON 科学状态：发现脱靶即表示计算已成功完成。有关 screen 特定的退出码，请参见输入契约。

引用 Scientific Agent Skills

如果在已发表工作中使用，请引用 sources.md 中的上游方法以及 Scientific Agent Skills。报告复现实际分析所需的软件版本和检测特定设置。