dsh-molbio-tools

面向 DeepSeek Harness 的零依赖分子生物学研究插件：序列分析、引物自动设计与检查、限制性酶切模拟、GenBank 解析与质粒图谱、qPCR 分析、文献助手与实验台计算。除文献检索与存储外全部为确定性纯计算；插件由纯 .mjs 文件构成，可随 agent preset 目录整体复制分发。

提供的工具（44 个，模型可调用）

序列分析

引物

质粒

克隆构建

克隆验证

实验与统计

蛋白质

序列分析扩展

| 工具 | 功能 | | --- | --- | | molbio_align | Smith-Waterman 局部比对：可读的比对线（|/空格）、同一性%、比对区间、错配/缺失/插入列表 | | molbio_fasta_fastq | 工作区 FASTA/FASTQ 处理：条目统计（长度/GC）、按 id 提取（可写 FASTA）、FASTQ→FASTA 转换、FASTQ QC（Phred 均值/低质量比例/位点质量分布） | | molbio_extract_region | 从质粒文件按特征名（如 "AmpR"、"MCS"）或坐标提取子序列，可选反向互补与 FASTA 保存——克隆/设计的下游输入 |

多序列比对与保守性（v15）

图谱增强

• molbio_plasmid_map / molbio_plasmid_map_file 新增 gc_skew: true（GC skew 环）与 show_unique_cutters: true（绿色标记所有单切酶）

文献助手

文献与记录

目录结构

dsh-molbio-tools/
├── index.mjs        # 插件入口：export { name, inject, apply }，注册 44 个工具
├── lib.mjs          # 基础库：IUPAC、翻译、酶表（含双链向切点查找）、NN 热力学、qPCR、lab math
├── design.mjs       # 引物自动设计（含跨内含子 qPCR）
├── genbank.mjs      # GenBank flatfile 解析器
├── snapgene.mjs     # SnapGene .dna 二进制解析器（含极简 XML 扫描器）
├── plasmid.mjs      # SVG 质粒图谱渲染器（环形/线形，GC skew/标记）
├── align.mjs        # Smith-Waterman 局部比对 + 锚点窗口（Sanger 验证用）
├── msa.mjs          # 多序列渐进式比对（仿射缺口 NW + UPGMA）与保守性分析
├── cloning.mjs      # 克隆模拟：选酶/酶切连接/Gibson/Golden Gate/克隆引物/突变引物
├── sanger.mjs       # ABIF (.ab1) 解析 + 测序验证报告
├── protein.mjs      # 蛋白性质/肽段酶切/密码子优化
├── plot.mjs         # SVG 柱状/散点图 + 虚拟琼脂糖凝胶渲染
├── seqio.mjs        # FASTA/FASTQ 解析与统计
├── records.mjs      # 协议库/实验日志存储
├── papers.mjs       # 文献库存储（经 harness fs 服务 + 沙箱政策）
├── view.mjs         # 自动查看：把生成的 SVG 交给系统默认应用打开（镜像 host.openPath 语义）
├── cordis.patch.yml # bundle 补丁层（可选安装渠道用，按包名插入 tool-molbio 行）
├── preset/
│   └── molbio-lab/  # 推荐的专属模式预设（agent.cordis.yml + preset.yml + plugins/dsh-molbio-tools-v15/）
├── test/
│   └── smoke.mjs    # 冒烟测试（复用 harness 自身的 JSON Schema 校验器）
├── docs/
│   └── maintainer.md # 维护者文档（合规对照/开发测试/路线图）
├── package.json
└── README.md

安装（推荐：专属模式 preset）

推荐给最终用户的方式：安装后预设选择器出现 Molecular Biology Lab 专属模式， molbio 工具只在该模式出现，不会把 44 个工具和提示段注入到其它会话（避免污染无关场景）。

仓库的 preset/molbio-lab/ 即完整预设目录，把它复制到对方的 harness 用户目录即可：

~/.dsh/.agent-presets/molbio-lab/
├── agent.cordis.yml                 # 标准编码 Agent + 末尾的 tool-molbio 行
├── preset.yml                       # 显示名称与描述
└── plugins/
    └── dsh-molbio-tools-v15/        # 插件文件（版本目录，见下文）

对方重启（或刷新预设列表）后，在预设选择器中选择 Molecular Biology Lab 新建会话。

插件更新（版本目录规则）

DSH 的 standing 挂载按 ESM 模块 URL 缓存模块。每次更新必须新建版本目录 （如 dsh-molbio-tools-v15/）并同步修改 agent.cordis.yml 中的插件行；绝不在已发布 目录里原地改文件。分发者从包根目录把 .mjs 文件复制进新版本目录即可：

cp *.mjs preset/molbio-lab/plugins/dsh-molbio-tools-v15/
# 并把 agent.cordis.yml 的行改为 './plugins/dsh-molbio-tools-v15/index.mjs'

安装（可选：官方组合包 bundle，全局可见）

本包同时是官方的组合包（bundle）（dsh.bundle manifest → cordis.patch.yml）。 注意：bundle 把插件行注册到 profile 的全局 tools 层——该 profile 的所有会话都会 加载 molbio 工具与提示段。适合"整个 profile 专用于分子生物学"的用户，不适合混合用途。

验证方式（官方推荐）：

dsh plugin --profile demo add <包>      # 需要用户机器装有 pnpm（官方流程依赖）
dsh --profile demo --dump-config        # 组合树中应出现 "# == dsh-molbio-tools" 层

本仓库已验证：--dump-config 输出以 # == dsh-molbio-tools + - id: tool-molbio / name: dsh-molbio-tools 开头（层序在 dsh-base 之上），且从 profile 目录按包名 import('dsh-molbio-tools') 成功注册全部 39 个工具。两种安装方式可以共存（同名工具 由 preset 层 shadow 全局层，无冲突），但通常二选一即可。

> 版本目录规则的原理（维护者必读）：DSH 的 standing preset 挂载在整个进程生命周期 > 内存在，且 Node 的 ESM 模块缓存以文件 URL 为键——同一 URL 的 import() 永远返回 > 第一次加载的模块，包括插件内部的相互 import（给入口加查询串只能破坏入口自身的 > 缓存，依赖文件仍会命中旧缓存）。因此原地替换 .mjs 不会让新会话加载新代码；目录名 > 变化使所有模块 URL 一次性更新。旧目录可删除（已运行的 generation 持有内存中的模块， > 不受磁盘删除影响）。

行为与假设

• 纯计算工具（序列/引物/统计）确定性、无副作用；输入输出均为可持久化的 JSON。
• 图谱工具直接写文件：molbio_plasmid_map / molbio_plasmid_map_file 把 SVG 写入工作区（ctx.fs + 会话沙箱政策），模型上下文里只出现文件路径，避免大文本截断。
• 自动查看（auto-view）：所有生成图片的工具（molbio_plasmid_map、molbio_plasmid_map_file、molbio_clone_simulate/molbio_golden_gate 的 map_path、molbio_qpcr_efficiency 的 plot_path、molbio_plot、molbio_virtual_gel）写完 SVG 后自动用操作系统默认应用打开（Windows 为 Invoke-Item、macOS 为 open、桌面 Linux 为 xdg-open/$BROWSER、WSL 自动转译为 Windows 路径），结果中的 auto_viewed 字段报告交接是否成功。每调用可用 auto_view: false 关闭；无桌面环境（headless Linux）与 MOLBIO_AUTO_VIEW=0 时自动跳过。
• 克隆模拟约定：酶切-连接要求"插入片段按 5'→3' 书写、上游酶在 5' 端"；单酶连接会给出双向连接说明与两种方向的验证酶切；特征坐标按插入/缺失自动平移，跨越连接点的特征标注 spans_insertion。
• Sanger 验证：参考序列按环状处理（读段跨 origin 也能正确对齐）；.ab1 低质量（<20）位点单独标注且不计入"differences_found"判定；氨基酸后果按 frame 1 假设报告。
• 文献库与检索走 harness 的 fs/web 服务：库文件默认 papers.json 在工作区内，写入遵循会话的沙箱政策（ctx.sandboxPolicy），与其他文件工具同权。
• IUPAC 序列：输入支持 A C G T U R Y S W K M B D H V N；U 按 T 处理；简并碱基在酶切位点匹配与引物设计中视为不匹配/不可用。
• Tm 是估算值：SantaLucia 1998 NN + 盐校正，报告时应说明是估算，不能替代仪器校准。
• 图谱坐标：特征 1-based 闭区间；strand: -1 表示 complement 链；酶切标记使用酶表的标准切点记号。
• 引物设计性能：区域扫描 + 候选缓存 + 排序裁剪，几十 kb 模板在亚秒级完成；找不到满足约束的组合时返回空并提示放宽条件。
• 错配容差（v12）：max_mismatches > 0 时，若某窗口没有精确引物通过全部约束，设计器用最少的替换尝试挽救（只针对可修复的约束：GC 失衡、run、Tm 微差）。3' 末端碱基永远不错配，默认在 3' 端 mismatch_3prime_zone（默认 5 bp）关键区内也不放错配（max_3prime_mismatches 可放宽）。每处错配逐条报告：引物内位置、模板位置、模板碱基/引物碱基、距 3' 端距离；每个错配都会加重排序罚分——存在精确引物时精确引物永远优先。
• Primer3 对齐的结构筛查（v12）：自互补（self-any/self-end）为比对分（match +1 / mismatch −1 / gap −0.25，阈值 8.0/3.0）；发夹与引物二聚体（any/end）用与 Tm 相同的 SantaLucia NN 参数折成 Tm（默认阈值 47 °C，max_hairpin_tm/max_dimer_tm/max_dimer_end_tm）；3' 端稳定性 = 末 5 碱基的 ΔG(37 °C)（max_end_stability，默认 9 kcal/mol）；末 5 碱基 GC 数（max_end_gc，默认 5）；GC clamp 为 0-3 连续 G/C 分级（gc_clamp，默认 1，require_gc_clamp 为兼容别名）。数值均为估算，与 Primer3 同量纲便于互相校验。
• 非特异结合检查（v12）：check_mispriming: true 时，按 k-mer 索引检查每条引物 3' 尾（默认 8 bp、允许 1 个错配且末端碱基必须配对）在模板双链上的额外退火位点；超过 mispriming_max_sites 的引物对被拒绝，其余按位点数罚分并在 mispriming_sites 中报告位点与链向。
• 反应条件旋钮（v13）：两个设计工具暴露 na_mm/mg_mm/dntp_mm/primer_nm（默认 50/1.5/0.8/200，与 README 旧版固定值一致），直接驱动 Tm 模型的 von Ahsen 2001 盐校正与发夹/二聚体折叠浓度；输出 conditions 回显实际使用的条件。
• 3' 目标位置偏好（v13）：target_position（模板坐标，跨内含子设计为剪接坐标）+ target_penalty 按"较近引物 3' 端到目标的距离"加重排序罚分，用于 SNP 分型/定点设计；每对与每条引物报告 target_distance。无目标时该字段不出现。
• 酶目录与双链向切点（v13）：molbio_enzyme_lookup 报告 IIS 酶在反向识别位点（如 BsaI 对 GAGACC）的切点——这是 molbio_restriction_sites 不报告的；molbio_golden_gate 的内部位点检查同样按双链向。
• Golden Gate（v13）：molbio_golden_gate 按标准 BsaI 类几何建模（识别位点 + filler + 4 bp 5' 突出端）：连接处不留识别位点，载体盒子的两个识别位点保留在骨架上（标准 destination 载体行为，下一级组装换另一种 IIS 酶）；输出质粒与特征坐标以反向切点为线性化起点（环状质粒，仅显示原点不同），fragments_to_order 给出可直接下单的片段序列。突出端设计确定性（按 |GC−2| 排序的 4-mer 池贪心选取），唯一、非回文、非互补，并回溯验证连接处不重建酶位点。
• 虚拟凝胶（v13）：molbio_virtual_gel 用 log₁₀ 迁移率模型绘制预期条带（2 + 2·log₁₀(bp) 条带粗细），是"预期图"而非真实胶的模拟。
• 多序列比对（v15）：molbio_msa_align 是启发式渐进比对——两两/谱比对用仿射缺口（开 −6/延伸 −2，match +4/mismatch −4）且末端缺口免费（半全局），合并顺序由 5-mer 距离的 UPGMA 树决定，谱-谱打分用和-对（sum-of-pairs，按列碱基计数，残基对缺口计 0 分）；合并时新缺口按"一旦有缺口、永远有缺口"整列延伸，末端悬挂则允许部分缺口列。输入限制 2-50 条、单条 ≤ 3000 bp、总长 ≤ 30000 bp；U 按 T 处理，简并碱基相同才计匹配（R vs A 不计）。输出顺序与输入一致。
• 保守性分析（v15）：列 identity = 最高频残基数/该列残基数（缺口不计入残基）；熵基保守性 = 1 − H/2（H 为 4 碱基分布（简并碱基按集合展开）的香农熵）；共识字符 = 最高频碱基（占比 ≥50%）否则为出现碱基集合的 IUPAC 简并码；全缺口列共识为 - 且计为保守。threshold（默认 0.8）以下列为可变位点（至多报告 200 个）；两两同一性 = 相同非缺口列/总列数（两个缺口不算匹配）。≤300 列时逐列详情附于 per_column。所有比对与打分均为用于比较的估算值，不是系统发育真值。

典型用法示例

"解析这个 .dna 文件并画出质粒图谱"        → molbio_plasmid_map_file(path, enzymes:[...]) → 工具直接写入 <名称>.svg
"看看 pUC118.dna 里有哪些特征和引物"      → molbio_parse_snapgene(path)
"把这段序列克隆进 pUC118（EcoRI/HindIII），模拟最终质粒" → molbio_unique_cutters 选酶 → molbio_clone_simulate → molbio_plasmid_map 画新质粒
"用 BsaI 把三个片段 Golden Gate 装进 pL1" → molbio_golden_gate(vector, inserts:[...], replace_region:{...}) → fragments_to_order 下单 + save_path/map_path
"我的载体里 BsaI 会不会把插入片段切了？" → molbio_enzyme_lookup(sequence: 片段, enzymes:[BsaI])
"酶切应该出哪几条带？画个图" → molbio_restriction_sites → molbio_virtual_gel(lanes:[{fragments}])
"给插入片段设计带酶切位点的克隆引物"      → molbio_clone_primers
"帮我验证这个测序结果和质粒是否一致"      → molbio_verify_sanger(trace_path, reference_path)
"帮我在外显子 3 上设计一对 qPCR 引物，产物 80-150 bp" → molbio_design_primers (amplicon_min/max) → molbio_primer_check 复核
"把这几条同源序列对齐，找出保守区和可变位点" → molbio_msa_align(sequences:[…]) → molbio_conservation(alignment: 比对结果) 或直接 molbio_conservation(sequences:[…])
"搜一下 KRAS G12D 抑制剂的最新文献并存进阅读库" → molbio_pubmed_search → molbio_paper_add

SnapGene .dna 支持说明

• 解析器支持现代 SnapGene 格式（cookie + DNA 包 + XML 包：features 0x0A、primers 0x05、notes 0x06）；序列编码自动检测（ASCII 与旧式数字编码）；环状/线形由 DNA 包 flags 推断。
• 特征区段支持多段 join（如 AmpR 的编码区 + 信号肽），directionality 映射为链向（1→正链，2→负链）。
• SnapGene 注释里的 HTML 文本（<html>…）会自动清洗为纯文本。
• .dna 是二进制文件，普通 read 工具读不了——请直接给工具传文件路径，不要尝试自己读内容。

---

维护者（开发者）请参阅 [docs/maintainer.md](docs/maintainer.md)：官方规范对照、冒烟测试与发布/版本目录维护流程。