AnnoLens

不用写代码，也不用记命令。把基因 ID 或基因组位置交给 Agent，它像人工审阅员一样看证据、修基因模型。

中文 | English

这是什么

AnnoLens 是面向 AI Agent 的基因模型审阅与修复工具。自动注释流程（EVM、BRAKER、MAKER 等）给出的基因模型里，总有一部分有问题：截短、被拆成两段、两个基因被并成一个、缺起始或终止密码子、没有 UTR；还有一些基因根本没被注释出来。人工审阅员会在基因组浏览器里对照转录本、同源蛋白和剪接读段，逐个改正，例如用 GSAman，这非常耗费人力和专业判断。AnnoLens 把这个过程交给能看图的大模型，同时保证它不能乱改：

• 看证据图做判断：每个基因或位点一张证据图（当前模型、各样本转录本、同源蛋白投影、剪接读段）和一份文字证据表。

• 技能规定怎么审：先定基因范围，再定结构；什么时候保留、修改、拆分、新增或判为无法判断，都写在版本化的技能里。

• 引擎守住硬规则：候选只能取自观测转录本或完整同源投影，模型不能自己写坐标；完整 ORF、经典剪接、不与邻基因冲突、证据支持等由引擎检查。

• 只提建议，不改原件：输出审阅记录和候选 GFF3，基因组和输入注释都不会被修改。

它提供 Agent 插件（技能 + MCP Server）和 CLI 两种入口，全部在你自己的电脑上运行。

适合谁

• 刚做完基因组注释、需要检查和修正基因模型的课题组。

• 想把人工审阅（GSAman、Apollo、IGV 手工修改）的工作量降下来的人。

• 需要在 Codex、Claude Code、Cursor 等 Agent 里直接问“这个基因对不对”的研究者。

如果你需要的是从零做结构注释，请用 BRAKER、MAKER 等注释流程；AnnoLens 审阅和修复已有注释。

Related MCP server: mdreview-service

能做什么

开始使用

Agent 插件

将下面这句话发给 Codex、Claude Code、Cursor、WorkBuddy 等 Agent：

帮我安装或更新这个插件：https://github.com/forageseed/AnnoLens

Agent 会按仓库里的 AGENTS.md 安装 Python 包、登记 MCP 服务并装好技能。安装完成后，先检查本机环境：

annolens check

然后直接描述任务，例如：

这个基因模型对吗？gene_123

把待审队列里的前 20 个基因审一遍，最后汇总一下。

CLI / MCP

需要 Python 3.11 或更新版本，Linux、macOS 或 Windows 的 WSL。安装和一个项目的完整流程：

python -m pip install git+https://github.com/forageseed/AnnoLens.git
annolens check
annolens prepare --manifest annolens.toml --threads 16    # 生成工作目录（剪接、同源投影、读段位点）
annolens scan    --manifest annolens.toml                 # 全基因组规则初查，生成待审队列

项目清单从 examples/annolens.toml 复制修改：基因组、注释、RNA 比对、同源蛋白，可选长读长转录本、HiFi、重复序列注释和模型接口。同源投影需要 miniprot；只有 BAM 没有 GTF 的样本还需要 StringTie。

接入支持 MCP 的客户端只需要一条命令（标准配置见 .mcp.json）：

{ "mcpServers": { "annolens": { "command": "annolens", "args": ["mcp"] } } }

项目路径取自环境变量 ANNOLENS_MANIFEST，没有设置时用启动目录下的 annolens.toml。也可以一步登记并装技能：annolens install --host codex|claude|cursor|generic --manifest annolens.toml。

不在对话里、要成批审阅时（模型密钥只从环境变量读取）：

annolens review  --manifest annolens.toml --queue P1 --workers 4
annolens addgene --manifest annolens.toml --queue missing_high --workers 4

你会得到什么

• 结论：每个基因或位点一条审阅记录（JSON），写明结论、置信度、理由和证据缺口。

• 候选模型：修改、拆分和新增的基因输出为 GFF3（含 UTR），每个都经过引擎验证。

• 证据图：对话里直接附上，便于人工复核。

• 读段核查：任意位置的 HiFi 与 RNA 读段计数，区分组装错误与真实移码或终止。

• 队列与汇总：全基因组初查的分级队列，批量审阅的结论统计。

与人工审阅对比

上图：a 为 AnnoLens 框架（代理提议、引擎逐项验证，审阅循环每次处理一个基因或位点）；b 为 20 个位点与独立注释的一致性；c 为汇总。

同一套基因组上选 20 个位点，覆盖截短、延伸、合并、拆分、缩短、非经典剪接、基因组移码、漏注释和对照共 9 类问题。AnnoLens（技能 v3.8，GLM 模型）自动审阅；GSAman 由 Agent 操作其图形界面逐个修改，操作时看不到 AnnoLens 的结果（不是资深人工审阅员，熟练的人可能更快）。参照为同物种另一套独立注释（不是绝对真值）。

分类型看：

• 截短的延长、相邻基因合并、新增基因，两者大多给出完全相同的模型。

• 拆分融合基因（2 个）、需要读阅读框才能判断的合并、负链新增基因，GSAman 的最长 ORF 预测做不出来，AnnoLens 都给出了与独立注释一致的结果。

• GSAman 在 1 个位点延长得更多（AnnoLens 证据门控没有放行）。

• GSAman 在 1 个位点误删了相邻基因。

• 非经典剪接和基因组移码，两者都保留原模型。

这次对比中发现的放行条件已经并入技能 v3.8：多个样本一致的完整 ORF 可以证明原模型被截短。

使用边界

• 需要 Linux、macOS 或 WSL：引擎用 pysam 读 BAM，pysam 没有 Windows 原生版本。

• 需要宿主模型能看图；只有文字证据表时，判断能力会下降。

• 证据决定上限：某个结构没有任何转录本或完整同源蛋白支持时，AnnoLens 不会凭空构建，而是判为无法判断并写明缺什么证据。

• 非经典剪接位点不会被自动采纳，需要人工复核。

• 它只输出建议：最终注释是否采纳由你决定，基因组和原注释不会被改动。

• 批量审阅会调用你配置的模型接口并产生费用；在 Agent 对话里使用时由宿主模型完成审阅。

进阶参考

不要把当初用作注释证据的蛋白组设为 independent：它会重复注释里同样的截短。

• 结构只能取自观测证据：模型只能选“用哪条转录本”“哪个 ATG”“哪条同源投影”，不能直接写坐标。

• 证据门控：长读长全链支持；或内含子有读段支持、起止和长度有同源投影锚定；或多数样本一致的主导 ORF。至少满足一条才能采纳。

• 只修确实有问题的模型：完整且已有证据支持的模型不被替换；例外是截短证明，即有长度相符的同源蛋白、原模型不足其 90%，且起止由同源投影或至少 5 个样本一致的主导 ORF 锚定。

• 防截短：比主导 ORF 短、支持样本也更少的候选不能采纳。

• 可追溯：每个候选带内容哈希、引擎哈希和输入指纹；证据或代码一变，旧候选自动作废。

skills/annolens/
  SKILL.md                    什么时候用、怎么连接、工作流程
  references/gene-policy.md   已有基因的审阅策略（含拆分）
  references/locus-policy.md  缺失位点的新增基因策略
  references/decisions.md     各类结论的含义和机器规则
  references/tools.md         MCP 工具参考
  references/setup.md         安装与连接
  scripts/check_gff.py        不依赖 MCP 的确定性检查（任意 GFF3 + FASTA）
agents/annolens-curator.md    子 agent：审一个基因或位点
agents/annolens-batch.md      子 agent：审一个队列并汇总
commands/                     /annolens-review、/annolens-addgene、/annolens-queue

另有提示词 annolens_review_gene、annolens_add_gene，资源 annolens://skill/gene、annolens://skill/locus。

annolens/            Python 包（engine、session、mcp_server、check、install 等）
annolens/skills/     版本化技能文本（gene_v3.8；旧版 v3.7、v3.5 保留；locus_v3.6）
examples/            项目清单示例
skills/ agents/ commands/   技能包、子 agent、斜杠命令
.mcp.json .claude-plugin/ .codex-plugin/ server.json npm/   各宿主接入
AGENTS.md            给 Agent 的安装说明

引用与许可

论文准备中。许可证：Apache-2.0。