dsh-molbio-tools 0.22.2 → 0.24.0

package/cordis.patch.yml

@@ -47,7 +47,7 @@
         id: molbio-lab
         order: 5
         name: Molecular Biology Lab
-        description: "分子生物学专属模式：标准编码能力 + 60 个 molbio_* 工具（序列分析、引物设计（含跨内含子 qPCR、盐/浓度旋钮与目标位置偏好）、TaqMan 水解探针（含 MGB 与订购 CSV）与多重 PCR 互扰/退火温度/浓度建议、克隆模拟与选酶（含 Golden Gate）、酶目录查询、甲基化敏感位点与双酶切 buffer 兼容检查、多序列比对（每个输入残基都会进比对结果）、保守性分析与比对后处理（共识/缺口修剪/同一性矩阵/逐列覆盖度，含 sequence logo 图）、CRISPR gRNA 设计（SpCas9/SaCas9/Cas12a/Cas13，家族特定 PAM/PFS/种子）与脱靶搜索、SnapGene/GenBank 解析与质粒图谱、Sanger 测序验证、蛋白性质/密码子优化/螺旋轮投影与疏水性图、qPCR 与绘图、虚拟凝胶、实验台分析（FASTQ 质控、密码子使用、系统发生树（长叶名自动折行）、in-silico PCR、CpG/GC 组成、批量文件分析/CSV）、静默酶切位点突变设计——生成的 SVG 图片自动用系统默认应用打开，文献/协议/实验记录）。"
+        description: "分子生物学专属模式：标准编码能力 + 64 个 molbio_* 工具（序列分析、引物设计（含跨内含子 qPCR、盐/浓度旋钮与目标位置偏好）、TaqMan 水解探针（含 MGB 与订购 CSV）与多重 PCR 互扰/退火温度/浓度建议、克隆模拟与选酶（含 Golden Gate）、酶目录查询、甲基化敏感位点与双酶切 buffer 兼容检查、多序列比对（每个输入残基都会进比对结果）、保守性分析与比对后处理（共识/缺口修剪/同一性矩阵/逐列覆盖度，含 sequence logo 图）、CRISPR gRNA 设计（SpCas9/SaCas9/Cas12a/Cas13，家族特定 PAM/PFS/种子）与脱靶搜索、SnapGene/GenBank 解析与质粒图谱、Sanger 测序验证、蛋白性质/电荷-pH 曲线/密码子优化/螺旋轮投影与疏水性图、qPCR 与绘图、虚拟凝胶、实验台分析（FASTQ 质控、密码子使用、系统发生树（长叶名自动折行）、in-silico PCR、CpG/GC 组成、序列 dotplot、载体/接头污染筛查、FASTQ 修剪/过滤、批量文件分析/CSV）、静默酶切位点突变设计——生成的 SVG 图片自动用系统默认应用打开，文献/协议/实验记录）。"
         plugins:
           - id: persona
             name: '@deepseek-ai/dsh-persona'
@@ -67,6 +67,11 @@
             disabled: !!js process.platform !== 'win32'
           - id: tool-fs
             name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              # Set false to drop the apply_patch tool beside edit. (0.2.2-rc.1 makes this
+              # explicit in the shipped standard preset; the package default is false, and
+              # the row is kept verbatim so the two stay comparable.)
+              applyPatch: false
           - id: tool-fs-search
             name: '@deepseek-ai/dsh-tool-fs-search'
             config:
@@ -129,14 +134,13 @@
             config:
               - id: tool-subagent-control
                 name: '@deepseek-ai/dsh-tool-subagent-control'
-              - id: tool-subagent-list-agents
-                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
               - id: tool-subagent
                 name: '@deepseek-ai/dsh-tool-subagent'
                 config:
                   provider: spawn
                   toolName: subagent
-                  modelSelectionSettings: true
+                  modelSelection: true
+                  modelDiscovery: true
               - id: tool-subagent-fork
                 name: '@deepseek-ai/dsh-tool-subagent'
                 config:
@@ -168,7 +172,7 @@
             name: '@deepseek-ai/dsh-plugin-market/tools'
             disabled: true
 
-          # dsh-molbio-tools: molecular-biology toolset (60 tools across sequence
+          # dsh-molbio-tools: molecular-biology toolset (64 tools across sequence
           # analysis, primers (incl. TaqMan probes and multiplex compatibility),
           # in-silico PCR, cloning (incl. Golden Gate), enzyme catalog, methylation-aware
           # and double digests, plasmids, Sanger verification, proteins (incl. helical

package/design.mjs

@@ -36,17 +36,17 @@
  *     from `anchor` and not from the RC-scan `start`. It is the REVERSE primer,
  *     and the amplicon ends at `anchor + length - 1`.
  *
- * NOTE — `designIntronSpanningPrimers` (tool: `molbio_design_intron_primers`)
- * deliberately does NOT follow this convention and is unchanged in 0.16.0: it
- * reports both primers as sense substrings of the spliced transcript, which is
- * what makes its `exon`/`junction_left`/`junction_right` geometry, its
- * spliced-vs-genomic mismatch report and its 3'-tail mispriming check read
- * uniformly on one sequence. Both ends are therefore reported 5'->3' on the
- * sense strand, `forward` is downstream of `reverse`, and the molecule to order
- * as the reverse primer is the reverse complement of the reported `reverse`.
- * That is a real usability wart, not a silent one (nothing feeds this pair to
- * `molbio_pcr_simulate`), so it is recorded on the roadmap rather than changed
- * in the same release that moves `designPrimerPairs`.
+ * `designIntronSpanningPrimers` (tool: `molbio_design_intron_primers`)
+ * follows the SAME convention since 0.23.0. The junction is carried by the
+ * REVERSE primer (the assay sits 5' of the junction), so the reverse candidate
+ * is scanned on the reverse complement of the spliced transcript: every 3'-end
+ * constraint is then evaluated on the molecule that is ordered, and the hit is
+ * mapped back to sense coordinates through `anchor` (its 3' end, the LEFT edge
+ * of its site). `forward` is upstream of `reverse`, the spliced amplicon runs
+ * from the forward 5' end to the reverse 5' end, and the reported reverse
+ * sequence is what goes on the order form. Before 0.23.0 the tool reported both
+ * primers as sense substrings, so `forward` sat downstream of `reverse` and the
+ * reported reverse was the reverse complement of the molecule to order.
  */
 
 import {
@@ -738,37 +738,60 @@ export function designPrimers(rawTemplate, rawOptions) {
 // ── cross-intron primer design ──────────────────────────────────────────────
 
 /**
- * Mismatch report for cross-intron candidates. Both primer scans run on the
- * spliced transcript in the sense orientation (the reported reverse.sequence
- * follows the established sense-substring convention of this tool), so the
- * mapping is uniform: `template_base` is what a perfectly matching primer
- * carries at the position on the spliced transcript, and coordinates come back
- * both spliced and genomic.
+ * Mismatch report for cross-intron candidates. The forward primer is the
+ * sense-strand substring at its binding site; the reverse primer is the REVERSE
+ * COMPLEMENT of the sense-strand substring at its site (the molecule that is
+ * ordered). `anchorStart` is the 0-based sense-strand position of the primer's
+ * 3' end — for the reverse primer that is the LEFT edge of its site — and
+ * `isReverse` flips both the perfect-match base and how a primer offset maps
+ * onto the transcript.
  */
-function intronMismatchReport(candidate, spliced, splicedToGenomic) {
+function intronMismatchReport(candidate, spliced, splicedToGenomic, anchorStart, isReverse) {
   const len = candidate.length;
-  return candidate.mismatches.map(({ p, base }) => ({
-    position: p + 1,
-    template_base: spliced[candidate.start + p],
-    primer_base: base,
-    spliced_position: candidate.start + p + 1,
-    genomic_position: splicedToGenomic[candidate.start + p] + 1,
-    distance_from_3prime: len - 1 - p,
-  }));
+  return candidate.mismatches.map(({ p, base }) => {
+    const offset = isReverse ? len - 1 - p : p;
+    const index = anchorStart + offset;
+    return {
+      position: p + 1,
+      template_base: isReverse ? complement(spliced[index]) : spliced[index],
+      primer_base: base,
+      spliced_position: index + 1,
+      genomic_position: splicedToGenomic[index] + 1,
+      distance_from_3prime: len - 1 - p,
+    };
+  });
 }
 
 /**
- * Design qPCR primer pairs where the forward primer spans an exon-exon
- * junction (>= min_junction_bases on each side) so genomic DNA cannot be
- * amplified, and the reverse primer sits in a different exon. Coordinates are
- * reported both on the spliced transcript and on the genomic sequence.
+ * The same weights as `mismatchPenalty`, over the snake_case report fields.
+ * The old intron path handed snake_case reports to the camelCase helper, so the
+ * 3'-zone surcharge never applied there; this keeps the two conventions apart on
+ * purpose instead of loosening the shared helper.
+ */
+function intronMismatchPenalty(report, zone) {
+  return report.reduce((sum, mismatch) => sum + 8 + (mismatch.distance_from_3prime <= zone ? 4 : 0), 0);
+}
+
+/**
+ * Design qPCR primer pairs across an exon-exon junction so genomic DNA cannot
+ * be amplified: the REVERSE primer straddles the junction (>= minJunctionBases
+ * on each side), the FORWARD primer sits upstream inside a single exon, and the
+ * spliced amplicon crosses the junction inside the reverse primer's site.
+ *
+ * Coordinates are reported both on the spliced transcript and on the genomic
+ * sequence. Orientation follows `designPrimerPairs` (see the file header):
+ * `forward.sequence` is the sense-strand substring at its site and
+ * `reverse.sequence` is the reverse complement of the sense-strand substring at
+ * its site. The reverse candidate is scanned on the reverse complement of the
+ * spliced transcript, so every 3'-end constraint (GC clamp, end stability, end
+ * GC, self-end, hairpin) applies to the molecule that is ordered.
  */
 export function designIntronSpanningPrimers(genomic, exons, opts) {
   if (!Array.isArray(exons) || exons.length < 2) throw new MolbioInputError('exons must be an array of at least two {start, end} spans');
   const sorted = [...exons].sort((a, b) => a.start - b.start);
   for (const exon of sorted) {
     if (!Number.isInteger(exon.start) || !Number.isInteger(exon.end) || exon.start < 1 || exon.end > genomic.length || exon.start > exon.end) {
-      throw new MolbioInputError(`exon ${JSON.stringify(exon)} is outside the genomic sequence (length ${genomic.length})`);
+      throw new MolbioInputError('exon ' + JSON.stringify(exon) + ' is outside the genomic sequence (length ' + genomic.length + ')');
     }
   }
   for (let i = 1; i < sorted.length; i++) {
@@ -791,33 +814,39 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
     }
   });
   if (spliced.length < 24) throw new MolbioInputError('the spliced transcript is too short for primer design');
+  const splicedLength = spliced.length;
+  const rcSpliced = reverseComplement(spliced);
 
   // v13 target position preference (coordinates on the spliced transcript).
   const targetPosition = opts.targetPosition;
-  if (targetPosition !== undefined && (!Number.isInteger(targetPosition) || targetPosition < 1 || targetPosition > spliced.length)) {
-    throw new MolbioInputError(`target_position ${targetPosition} is outside the spliced transcript (length ${spliced.length})`);
+  if (targetPosition !== undefined && (!Number.isInteger(targetPosition) || targetPosition < 1 || targetPosition > splicedLength)) {
+    throw new MolbioInputError('target_position ' + targetPosition + ' is outside the spliced transcript (length ' + splicedLength + ')');
   }
   const targetWeight = opts.targetPenalty ?? DESIGN_DEFAULTS.targetPenalty;
 
-  // Forward candidates must span a junction with minSide bases on each side.
-  const fwd = [];
-  for (const candidate of scanCandidates(spliced, 0, spliced.length - opts.lenMin, opts)) {
+  // Forward candidates: entirely inside one exon on the sense strand.
+  const fwd = scanCandidates(spliced, 0, splicedLength - opts.lenMin, opts)
+    .filter((candidate) => splicedToExon[candidate.start] === splicedToExon[candidate.start + candidate.length - 1])
+    .map((candidate) => ({ ...candidate, exon: splicedToExon[candidate.start] }))
+    .sort((a, b) => a.start - b.start);
+
+  // Reverse candidates: scanned on the reverse complement (the ordered
+  // molecule), then mapped back to the sense-strand 3' end `anchor`.
+  const rev = [];
+  for (const candidate of scanCandidates(rcSpliced, 0, splicedLength - opts.lenMin, opts)) {
+    const anchor = splicedLength - (candidate.start + candidate.length);
+    const topEnd = anchor + candidate.length - 1;
     for (const junction of junctionPositions) {
-      const left = junction.splicedPos - candidate.start;
-      const right = candidate.start + candidate.length - junction.splicedPos;
+      const left = junction.splicedPos - anchor;
+      const right = topEnd + 1 - junction.splicedPos;
       if (left >= minSide && right >= minSide) {
-        fwd.push({ ...candidate, junction, junction_left: left, junction_right: right });
+        rev.push({ ...candidate, anchor, junction, junction_left: left, junction_right: right });
         break;
       }
     }
   }
-
-  // Reverse candidates sit entirely inside one exon.
-  const rev = scanCandidates(spliced, 0, spliced.length - opts.lenMin, opts)
-    .filter((candidate) => splicedToExon[candidate.start] === splicedToExon[candidate.start + candidate.length - 1])
-    .map((candidate) => ({ ...candidate, exon: splicedToExon[candidate.start] }))
-    .sort((a, b) => a.start - b.start);
-  const revStarts = rev.map((candidate) => candidate.start);
+  rev.sort((a, b) => a.anchor - b.anchor);
+  const revAnchors = rev.map((candidate) => candidate.anchor);
 
   const tmCenter = (opts.tmMin + opts.tmMax) / 2;
   const misprimingIndex = opts.checkMispriming
@@ -826,48 +855,52 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
   const maxSites = opts.misprimingMaxSites ?? DESIGN_DEFAULTS.misprimingMaxSites;
   const pairs = [];
   for (const f of fwd) {
-    const fwdEnd = f.start + f.length - 1;
-    const aMin = fwdEnd - opts.ampliconMax + 1;
-    const aMax = fwdEnd - opts.ampliconMin + 1;
+    // The reverse site must start after the forward 3' end, and the amplicon
+    // (forward 5' -> reverse 5') must fit the window. The bounds are widened by
+    // the primer-length range and the exact length is checked below, because a
+    // long reverse primer can start earlier and still close inside the window.
+    const aMin = Math.max(f.start + f.length, f.start + opts.ampliconMin - opts.lenMax);
+    const aMax = f.start + opts.ampliconMax - opts.lenMin;
+    if (aMax < aMin) continue;
     let lo = 0;
-    let hi = revStarts.length;
+    let hi = revAnchors.length;
     while (lo < hi) {
       const mid = (lo + hi) >> 1;
-      if (revStarts[mid] < aMin) lo = mid + 1;
+      if (revAnchors[mid] < aMin) lo = mid + 1;
       else hi = mid;
     }
     for (let i = lo; i < rev.length; i++) {
       const r = rev[i];
-      if (r.start > aMax) break;
-      if (r.exon === f.junction.down) continue; // reverse primer must sit in a different exon
-      const gEnd = splicedToGenomic[fwdEnd];
-      const gStart = splicedToGenomic[r.start];
+      if (r.anchor > aMax) break;
+      const ampliconStart = f.start;
+      const ampliconEnd = r.anchor + r.length - 1;
+      const ampliconLength = ampliconEnd - ampliconStart + 1;
+      if (ampliconLength < opts.ampliconMin || ampliconLength > opts.ampliconMax) continue;
+      const gStart = splicedToGenomic[ampliconStart];
+      const gEnd = splicedToGenomic[ampliconEnd];
       if (gEnd - gStart + 1 < minGenomicSpan) continue;
       if (Math.abs(f.tm - r.tm) > opts.maxTmDelta) continue;
       const dimer = dimerThermo(f.sequence, r.sequence, opts.ctMolar ?? DEFAULT_CT_MOLAR);
       if (dimer.any_tm > opts.maxDimerTm || dimer.end_tm > opts.maxDimerEndTm) continue;
+      const misK = opts.mispriming3PrimeBases ?? DESIGN_DEFAULTS.mispriming3PrimeBases;
       let fMispriming = { count: 0, sites: [] };
       let rMispriming = { count: 0, sites: [] };
       if (misprimingIndex !== undefined) {
-        const misK = opts.mispriming3PrimeBases ?? DESIGN_DEFAULTS.mispriming3PrimeBases;
-        fMispriming = misprimingForCandidate(f, f.sequence.slice(-misK), misprimingIndex, opts, f.start);
+        // Exclude each primer's own 3'-tail window (not its 5' end).
+        fMispriming = misprimingForCandidate(f, f.sequence.slice(-misK), misprimingIndex, opts, f.start + f.length - misK);
         if (fMispriming.count > maxSites) continue;
-        // the reported reverse sequence follows the sense-substring convention:
-        // the real oligo is its reverse complement, so its 3' tail is the RC
-        // of the FIRST k bases and the intended site is r.start
-        const rTail = reverseComplement(r.sequence.slice(0, misK));
-        rMispriming = misprimingForCandidate(r, rTail, misprimingIndex, opts, r.start);
+        rMispriming = misprimingForCandidate(r, r.sequence.slice(-misK), misprimingIndex, opts, r.anchor);
         if (rMispriming.count > maxSites) continue;
       }
-      const fMismatches = intronMismatchReport(f, spliced, splicedToGenomic);
-      const rMismatches = intronMismatchReport(r, spliced, splicedToGenomic);
+      const fMismatches = intronMismatchReport(f, spliced, splicedToGenomic, f.start, false);
+      const rMismatches = intronMismatchReport(r, spliced, splicedToGenomic, r.anchor, true);
       const zone = opts.mismatch3PrimeZone ?? DESIGN_DEFAULTS.mismatch3PrimeZone;
       let fTargetDistance;
       let rTargetDistance;
       let targetDistance;
       if (targetPosition !== undefined) {
-        fTargetDistance = Math.abs(f.start + f.length - targetPosition); // spliced 1-based 3' end
-        rTargetDistance = Math.abs(r.start + 1 - targetPosition);
+        fTargetDistance = Math.abs(f.start + f.length - targetPosition); // forward 3' end (1-based)
+        rTargetDistance = Math.abs(r.anchor + 1 - targetPosition);       // reverse 3' end (1-based)
         targetDistance = Math.min(fTargetDistance, rTargetDistance);
       }
       const penalty = 0.6 * Math.abs(f.tm - r.tm) + Math.abs(f.tm - tmCenter) + Math.abs(r.tm - tmCenter)
@@ -875,8 +908,8 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
         + 1.0 * Math.max(0, f.self_end - 1) + 1.0 * Math.max(0, r.self_end - 1)
         + 0.2 * Math.max(0, f.hairpin_tm - 40) + 0.2 * Math.max(0, r.hairpin_tm - 40)
         + 0.2 * Math.max(0, dimer.any_tm - 40) + 0.2 * Math.max(0, dimer.end_tm - 40)
-        + mismatchPenalty(fMismatches, zone)
-        + mismatchPenalty(rMismatches, zone)
+        + intronMismatchPenalty(fMismatches, zone)
+        + intronMismatchPenalty(rMismatches, zone)
         + 8 * fMispriming.count + 8 * rMispriming.count
         + (targetDistance !== undefined ? targetWeight * targetDistance : 0);
       pairs.push({
@@ -894,9 +927,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           spliced_end: f.start + f.length,
           genomic_start: splicedToGenomic[f.start] + 1,
           genomic_end: splicedToGenomic[f.start + f.length - 1] + 1,
-          exons: [String(f.junction.up + 1), String(f.junction.down + 1)],
-          junction_left: f.junction_left,
-          junction_right: f.junction_right,
+          exon: f.exon + 1,
           mismatch_count: fMismatches.length,
           mismatches: fMismatches,
           mispriming_count: fMispriming.count,
@@ -918,11 +949,13 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           hairpin_tm: r.hairpin_tm,
           end_stability_kcal: r.end_stability_kcal,
           end_gc_count: r.end_gc_count,
-          spliced_start: r.start + 1,
-          spliced_end: r.start + r.length,
-          genomic_start: splicedToGenomic[r.start] + 1,
-          genomic_end: splicedToGenomic[r.start + r.length - 1] + 1,
-          exon: r.exon + 1,
+          spliced_start: r.anchor + 1,
+          spliced_end: r.anchor + r.length,
+          genomic_start: splicedToGenomic[r.anchor] + 1,
+          genomic_end: splicedToGenomic[r.anchor + r.length - 1] + 1,
+          exons: [String(r.junction.up + 1), String(r.junction.down + 1)],
+          junction_left: r.junction_left,
+          junction_right: r.junction_right,
           mismatch_count: rMismatches.length,
           mismatches: rMismatches,
           mispriming_count: rMispriming.count,
@@ -934,7 +967,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           })),
           ...(rTargetDistance !== undefined ? { target_distance: rTargetDistance } : {}),
         },
-        spliced_amplicon: { start: r.start + 1, end: fwdEnd + 1, length: fwdEnd - r.start + 1 },
+        spliced_amplicon: { start: ampliconStart + 1, end: ampliconEnd + 1, length: ampliconLength },
         genomic_amplicon_length: gEnd - gStart + 1,
         ...(targetDistance !== undefined ? { target_distance: targetDistance } : {}),
         penalty: Math.round(penalty * 100) / 100,
@@ -945,7 +978,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
   const seen = new Set();
   const unique = [];
   for (const pair of pairs) {
-    const key = `${pair.spliced_amplicon.start}:${pair.spliced_amplicon.end}`;
+    const key = pair.spliced_amplicon.start + ':' + pair.spliced_amplicon.end;
     if (seen.has(key)) continue;
     seen.add(key);
     unique.push(pair);

package/docs/capability-gap-survey.md

@@ -6,6 +6,11 @@ mainstream bioinformatics landscape offer that this toolset does **not**, and wh
 deterministic algorithms in a few hundred lines of dependency-free JS with **no external data files,
 binaries, network, or reference databases**?
 
+> **Status note (0.24.0).** The baseline below is the 52-tool package this survey was written
+> against. Since then rows 1–7, 11, 12, 23, 30, 34, 40 and the Cas-family half of row 20 have shipped
+> (see [history.md](history.md) and the roadmap); the remaining rows are still candidates unless
+> §3 names a blocker. The rankings are left as written so the original judgement can be audited.
+
 **Method.** Surveyed nine source families (commercial plasmid/cloning suites; bench web calculators;
 Biopython/BioPerl/SeqKit/EMBOSS command-line toolkits; standard sequence/statistics analyses;
 microbiome; population genetics; protein prediction; alignment post-processing; sequencing QC),

package/docs/client-panel.md

@@ -13,6 +13,7 @@
 | **Molbio**（右栏 tab） | 列出会话工作区里的序列文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图 | `workspaceFiles.readAll`（二进制，含 SnapGene） |
 | **Papers**（右栏 tab） | 把 `molbio_paper_*` 工具维护的 `papers.json` 渲染成可搜索的阅读列表 + 详情面板（标题/作者/期刊/年份/PMID/URL/标签/笔记，标题链接到 PubMed 或原 URL） | `workspaceFiles.read`（文本） |
 | **图谱调用卡**（`tool.call.toolview`） | `molbio_plasmid_map` / `molbio_plasmid_map_file` 的调用卡：在对话里直接画出这次调用产出的图谱（摘要行 + 写入路径），失败时显示错误文本与 Inspect 入口 | 工具自己声明的 `output.presentationMeta`（见下） |
+| **图形调用卡**（`tool.call.toolview`） | `molbio_sequence_logo` / `molbio_grna_design` 的调用卡：logo 直接画图；gRNA 画 `map_path` 并列出前 5 条 guide（无 map 时仍有摘要与表格） | 同上，kind = `molbio-figure` |
 | **PubMed API key**（`plugins.detail.section`） | 插件 → 已安装插件 → `dsh-molbio-tools` 详情页里的一段表单：password 输入 + Save/Remove，状态只报「已配置 / 来源 / 未配置」，永不回显值 | `ctx.remote.credentials.describe` / `set` / `unset`（host 的凭据 seam） |
 
 **解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`），
@@ -47,11 +48,11 @@ SVG 随 meta 传输有上限（256 KB）：真实载体的图谱 20-60 KB，但
 | `build/client-bundle-core.mjs` | 打包器的**生成逻辑**（可 import）：`createGenerator({entry, baseDir})` → 模块图 + `renderBundle(packageName)`；`test/contract.mjs` 在进程内用它重算产物做新鲜度检查（不 spawn，受限沙箱下也能验证） |
 | `build/browser-api.mjs` | 浏览器安全面：从**包根的 `.mjs` 源文件**再导出面板可用的一切（单一事实来源） |
 | `build/panel-core.mjs` | 面板的数据通路（分类/解码/解析/渲染/文献库投影），不含 React，可在 Node 里单测 |
-| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，两个 map 工具的调用卡，以及插件详情页的 key 配置段 |
+| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，两个 map 工具与两个 figure 工具的调用卡，以及插件详情页的 key 配置段 |
 | `lib/client.js` | **构建产物**（`exports["./client"]` 指向它；由 `npm run build:client` 生成） |
-| `packages/molbio-panel/` | 面板专用包（宿主半边空实现），面板与 57 个工具解耦的交付通道 |
+| `packages/molbio-panel/` | 面板专用包（宿主半边空实现），面板与 64 个工具解耦的交付通道 |
 | `test/client.mjs` | 按加载器的方式执行产物 + 驱动两条数据通路（含真实 pUC118 夹具） |
-| `test/map-card.mjs` | 调用卡的**跨界**检查：真实工具的投影 → 卡片读取 → 渲染出 SVG（含四种降级路径） |
+| `test/map-card.mjs` | 调用卡的**跨界**检查：地图卡与图形卡（logo/gRNA）的真实投影 → 卡片读取 → 渲染出 SVG（含降级、超限、坏 meta 路径） |
 | `test/client-mount.mjs` | 复刻宿主侧图扫描，证明两个包都能挂上、依赖可解析 |
 
 命令：`npm run build:client`（构建）、`npm test`（全部测试）、
@@ -250,10 +251,11 @@ shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
 - **插件详情页的 key 配置**：✅ 已落地（0.22.1，见第 1 与第 4 节）。后续可把同一个
   `plugins.detail.section` 模式用于其它凭据（例如文献库的机构代理），前提是它们也有一个
   稳定的环境变量名。
-- **`tool.call.toolview`**：✅ 已落地（见第 1 与第 3 节），覆盖两个 map 工具。可继续做的
-  是给 `molbio_sequence_logo` / `molbio_grna_design` 之类的工具也加上卡片（同一套
-  `presentationMeta` + 卡片模式）。**注意上线前先跑 `test/client.mjs` 的抢座位顺序那一层**：
-  0.7.1 的卡片因为裸 `register()` 抢座位而让 GUI 起不来（0.7.2 修复，见 §4 第一条）。
+- **`tool.call.toolview`**：✅ 已落地（见第 1 与第 3 节），覆盖两个 map 工具与
+  `molbio_sequence_logo` / `molbio_grna_design`（0.23.0，`molbio-figure` 投影）。
+  后续可考虑把同样的卡片给 `molbio_dotplot` 等新画图工具。**任何新卡片上线前先跑
+  `test/client.mjs` 的抢座位顺序那一层**：0.7.1 的卡片因为裸 `register()` 抢座位而让 GUI
+  起不来（0.7.2 修复，见 §4 第一条）；`contract` 会从产物里的 key 表反推投影数。
 - **文献库写回**（可选）：若要面板内编辑笔记/标签，需要先定义与 `molbio_paper_*` 工具
   一致的并发契约（乐观版本号或串行化队列），或让工具走同一条 RPC。
 - **上游提案（路径 B）**：preset 渠道挂 client 仍是真实生态需求，可以在社区反馈时

package/docs/history.md

@@ -16,6 +16,8 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.24.0 | — | **数据卫生版**：新增 `molbio_contamination_screen`（内置载体/接头短签名，双链、0–2 错配）与 `molbio_fastq_trim`（质量/接头/引物/poly/N/长度，写 FASTQ/FASTA）；修 FASTQ QC 接头表 Small RNA 5' 的 RNA→DNA 静默错 | 62 → 64 |
+| 0.23.0 | — | **2.0 遗留修复 + 2.9a 调用卡 + 两个候选池工具**：跨内含子引物报告真实反向分子（F 在 R 上游）、logo/gRNA 调用卡、`molbio_protein_charge`、`molbio_dotplot`；同版完成 **DSH 0.2.2-rc.1 适配**（删掉上游已移除的 `list-agents` 子路径行、subagent 模型选择改用新键、守卫补上 specifier 解析） | 60 → 62 |
 | 0.22.2 | — | **DSH 0.2.1-rc.5 适配**：基线 rc.3 → rc.5（上游 standard 逐字节未变）；contract 声明守卫兼容桌面版裁掉 `lib/types` 的打包形态（+突变自检）；engines.node 与 CI 降到 24 | 60 |
 | 0.22.1 | — | **PubMed key 改走 DSH 凭据库**：解析顺序 `api_key` → 凭据库 → 环境变量；无凭据库时行为同 0.22.0 | 60 |
 | 0.22.0 | — | **DSH 0.2.1-rc.3 适配 + PubMed 官方 API**：`molbio_pubmed_search`/`_abstract` 支持 NCBI API key（E-utilities），无 key 行为不变 | 60 |
@@ -47,6 +49,66 @@
 
 ---
 
+## v0.24.0（2026-11-05，包 0.24.0）
+
+**三条教训，都关于“表/边界看起来对、实际不对”。**
+
+**(1) 接头表是 RNA，reads 是 DNA。** `fastq-qc.mjs` 的 Illumina Small RNA 5' 条目一直是
+`GUUCAG…`（RNA，含 U），而 `adapterContent` 直接拿它去 DNA reads 里做 `indexOf`。正向分子
+永远匹配不上，只有它的反向互补能命中，所以旧测试/使用中会看到“接头只报一半”。这不是算法错，
+是**数据表示**错：现在表放在 `contamination.mjs` 并以 DNA 形式定义（U→T），`fastq-qc` 只是
+导入/再导出；smoke 用正向与反向互补两条 read 断言两者都命中。
+
+**(2) 短签名筛查必须把“不是数据库”写进输出。** 内置表能回答“有没有 pUC/pET/attB/Illumina
+接头”，但不能回答“有没有未知载体”。描述、README 与 render 都写明：命中是线索，**未命中
+不等于干净**；默认 exact，`max_mismatches` 才启用 seed-and-verify（不扫描每个窗口）。
+
+**(3) 修剪工具的价值在“顺序与边界”，不在旋钮数量。** `molbio_fastq_trim` 固定 5' 引物 →
+3' 接头 → 3' 质量尾 → poly 尾 → 长度/N 的顺序，并把每个阶段的计数与条件回显在 `criteria` 里。
+不做 paired-end merge、semiglobal adapter alignment、UMI；这些另开工具比塞进一个“全能”工具
+更诚实。
+
+**顺带记录**：`seqio.mjs` 新增 `toFastq` 进了浏览器半的模块图，所以 0.24.0 虽然不改面板行为，
+仍重建了两个 `lib/client.js` 并把面板包 `0.1.8 → 0.1.9`；不 bump 会在发布时用同版本号发不同字节。
+定向模型跑分覆盖 `contamination-screen` 与 `fastq-trim`，两题 2/2（409,576 tokens，70 s；详见 CHANGELOG）。
+
+## v0.23.0（2026-10-31，包 0.23.0）
+
+三条教训，都关于"一个约定改了，哪些地方必须跟着改"。
+
+**(1) 方向不是标签问题，是约束落在哪个分子上的问题。** 跨内含子工具把两条引物都报成 sense
+子串，看起来只是"名字反了"；真正的代价是 GC clamp、末端稳定性、末端 GC、self-end 与发夹
+**全都检查在反向引物的 5' 端**（因为扫描方向反了），而报告的那条分子还不是要订购的。
+修法不是交换两个字段：反向候选要改到剪接转录本的**反向互补**上扫描，才让 3' 约束落到
+真正下单的分子上，再由 `anchor` 映回 sense 坐标。这也解释了为什么 smoke 夹具必须换 seed：
+旧夹具能在错误的约束下通过，改正后同一段序列不再产生合法候选。
+
+**(2) 两份字段命名（snake_case/camelCase）之间"看起来能跑"的调用，是静默失效的温床。**
+旧代码把 `mismatchReport` 的 `distance_from_3prime` 报告直接喂给读 `distanceFrom3Prime` 的
+`mismatchPenalty`，于是 3' 关键区加罚在跨内含子模式里**从未生效**——没有报错、没有测试红，
+只是排序少了一项。现在用专门的 `intronMismatchPenalty`，两种命名不再混用。
+
+**(3) 把"一个 key 列表"写成常量时，第二个列表不会自己出现。** 加调用卡时最容易漏的是
+守卫：`contract` 原本只读 `MAP_TOOL_KEYS`，新卡片的工具即使没有 `presentationMeta` 也照样绿。
+现在它从产物里的 `MAP_TOOL_KEYS` 与 `FIGURE_TOOL_KEYS` **两处**读 key，并用行首锚定的正则
+数投影——文件头注释里也提到 `presentationMeta(args, value)`，子串计数会把散文当成第四个实现。
+这类"守卫自己的样本过期"在 0.21.0 的 drift-probe 上已经付过一次账。
+
+**(4) 包还在，不等于行能挂载。** 0.2.2-rc.1 把 `list_agents` 并入了
+`@deepseek-ai/dsh-tool-subagent-control` 主入口，删掉了 `./list-agents` 子路径导出。preset 仍抄着
+rc.5 的那一行，而 `preset-health` 的 `packageInstalled` 只证明**包目录存在**，随后 import 的还是
+包根的 `exports["."]`——于是"包在、子路径没了"的行一路绿。真正的解析发生在 Loader 里
+（`import.meta.resolve`，受 `exports` 映射约束），所以现在的守卫先用 `createRequire(...).resolve`
+解析行名，再用 `no-such-subpath` 做突变自检。**组合树正确不代表行能挂载**，这和规则 1 记录的是
+同一类失败：静态检查看不见，只有真正解析/启动一次才会暴露。
+
+**顺带记录**：新工具的 pK 表与电荷函数从 `protein.mjs` 导出（`PK_SETS`/`netCharge`），
+而不是在 `protein-charge.mjs` 里复制一份；两个工具各自只加一条 benchmark 任务，
+`benchmark-coverage` 的 62/62 与 `benchmark-profile` 的 62 工具是同一批断言的两种读法。
+`dotplot` 的版式在收尾时从 720×720 改为 720×760（绘图区仍是 628 px 正方形），让 x 轴标题与
+图例各占一行；`test/smoke.mjs` 用几何断言盯住「标题不贴底、图例在画布内且在标题下方」。
+定向真实模型跑分（2026-11-05）覆盖 `intron-qpcr` / `protein-charge` / `dotplot`，三题 3/3。
+
 ## v0.22.1（2026-10-25，包 0.22.1）
 
 **环境变量不是唯一选择。** 0.22.0 只从 `api_key` 参数与 `process.env` 读 key；这一版把 DSH 的

package/docs/maintainer.md

@@ -30,13 +30,13 @@
 
 ## 60 秒速览
 
-- **包**：`dsh-molbio-tools`，零依赖 DSH 插件包，**60 个 `molbio_*` 工具**（其中
+- **包**：`dsh-molbio-tools`，零依赖 DSH 插件包，**64 个 `molbio_*` 工具**（其中
   `molbio_plot` 一个工具承载 8 种图表）。
-- **基线**：DSH **0.2.1-rc.5**；`package.json` 版本 0.22.2（DSH 桌面版内嵌 Node 24.21.0）。
+- **基线**：DSH **0.2.2-rc.1**；`package.json` 版本 0.24.0（DSH 桌面版内嵌 Node 24.21.0）。
 - **两条分发渠道**：根包（工具 + 面板）与 `packages/molbio-panel`（只面板），
   **两个独立的 npm 条目、两条独立的版本线**，必须分别发布。
 - **工具只在专属模式里出现**（设计如此）：bundle 的 `cordis.patch.yml` 只插一行**惰性宿主锚点**
-  （`molbio-client` → `./host.mjs`），60 个工具由同文件里的 preset insert 承载，
+  （`molbio-client` → `./host.mjs`），64 个工具由同文件里的 preset insert 承载，
   只会挂进 "Molecular Biology Lab" 模式。
 - **测试**：`npm test` = 插件（`smoke`）+ 画面（`svgpng`/`svgio`/`charts`）+ 客户端四套件 +
   DSH 契约（`contract`）+ 组合（`preset-health`）+ 漂移守卫（`drift-probe`）+
@@ -45,14 +45,14 @@
   `build/release-preflight.mjs`，然后用 **OIDC 可信发布**（仓库里没有任何长期 token）分两步发
   两个 npm 条目，最后用 CHANGELOG 该版本段落建 GitHub Release。**首次发布必须手动做一次**
   （可信发布要求包已存在），完整步骤见 [workflow.md](workflow.md) 第 4 节的 CD 段。
-- **benchmark**：`npm run bench` 用真实模型跑 core 档 14 题（`bench:full` 全部 61 题），分
+- **benchmark**：`npm run bench` 用真实模型跑 core 档 14 题（`bench:full` 全部 65 题），分
   `tools_ok` / `args_ok` / `answer_ok` 三项判分；`npm run bench:offline` 零成本校验期望值。
 
 包内目录结构：
 
 ```
 dsh-molbio-tools/
-├── index.mjs        # 插件入口：export { name, inject, apply }，注册 60 个工具
+├── index.mjs        # 插件入口：export { name, inject, apply }，注册 64 个工具
 ├── lib.mjs          # 基础库：IUPAC、翻译、酶表、NN 热力学、qPCR、lab math、甲基化/buffer 参考表
 ├── design.mjs       # 引物自动设计（含跨内含子 qPCR）
 ├── taqman.mjs       # TaqMan 水解探针设计（复用 design.mjs 的引物引擎）
@@ -60,6 +60,9 @@ dsh-molbio-tools/
 ├── methylation.mjs  # 甲基化敏感位点检查 + 双酶切 buffer 兼容
 ├── protein.mjs      # 蛋白性质 / 肽段酶切 / 密码子优化
 ├── protein-structure.mjs # 螺旋轮与疏水性图
+├── protein-charge.mjs # 电荷-pH 滴定曲线 + pI（两套 pK 表）
+├── contamination.mjs # 内置载体/接头短签名 + 双链污染筛查
+├── fastq-trim.mjs    # FASTQ 修剪/过滤（质量/接头/引物/poly/N/长度）
 ├── genbank.mjs      # GenBank flatfile 解析器
 ├── snapgene.mjs     # SnapGene .dna 二进制解析器
 ├── plasmid.mjs      # SVG 质粒图谱渲染器