内容
<div align="center">
<img src="https://raw.githubusercontent.com/coindef/Helix/main/docs/logo.svg" width="78" height="78" alt="Helix logo" />
# Helix
**一种用于可重复基因编辑设计的声明式DSL和编译器.**
[](https://pypi.org/project/helix-dsl/)
[](https://github.com/coindef/Helix/blob/main/LICENSE)
[](https://www.python.org/)
[](https://github.com/coindef/Helix/tree/main/tests)
[](#mcp-server)
[快速开始](#快速开始) · [亮点](#亮点) · [语言](#语言) · [架构](#架构) · [MCP服务器](#mcp服务器) · [深入了解](https://github.com/coindef/Helix/blob/main/ARCHITECTURE.md)
</div>
大多数基因编辑工具都是聊天接口，产生一次性的答案。
**Helix将编辑实验视为源代码：** 您编写一个小的声明式规范（意图），一个确定性的**编译器** — 借助狭义的LLM代理 — 将其转换为一个完全解析、具有溯源记录的**设计**，您可以
对其进行差异比较、版本控制、审查和重新运行。
<p align="center">
<img src="https://raw.githubusercontent.com/coindef/Helix/main/docs/hero.png" width="900"
alt="Helix 网页界面 — 左侧是语法高亮的规范编辑器；右侧是编译后的设计，带有排名导向和蛋白质后果徽章（过早停止、错义变异、沉默变异）。" />
</p>
> **关键规则：** 代理仅可以*发出或编辑规范*；只有确定性的编译器才能生成设计。这样可以保持信任边界的可审计性，并使每次运行都可重复 — 保护人类和代理的审计轨迹相同。
## 亮点
- 🧬 **8种模式** — 敲除 · 碱基编辑（CBE/ABE/CGBE） · 质粒编辑 · HDR敲入 · 双切删除 · CRISPRi / CRISPRa。
- 🎯 **约束是一等公民** — 编译器*解决*约束并报告不可行性，而不是默默地返回“前N个”。
- 🔬 **蛋白质后果感知** — 每个编码编辑都被调用*沉默 · 错义变异 · 过早停止（iSTOP） · 停止丢失 · 帧移位*，具有**保证同义**的HDR PAM块。
- 🧪 **变异感知导向** — 标记常见的种群SNPs在种子/PAM中（SNPs在其中会消除载体的结合）。
- 🔌 **可注入的后端** — 通过编辑规范而不是代码，交换启发式算法为实际工具（Cas-OFFinder、inDelphi、BE-Hive、PRIDICT、Ensembl/NCBI、ESMFold）。
- 🤖 **MCP服务器 + LLM代理** — 任何代理都可以通过规范→编译边界驱动编译器。
- 🖥️ **网页界面** — 语法高亮编辑器、交互式3D螺旋、现成寡核苷酸和结果分析。
- ♻️ **可重复和可审计** — 每个设计都带有溯源记录；可以在git中差异比较和版本控制。
## 快速开始
```bash
pip install helix-dsl # 或：pip install -e '.[all]'
helix compile examples/tp53_ko.hx -o out # 敲除（SpCas9）
helix compile examples/istop_base_edit.hx # 碱基编辑 → iSTOP敲除
helix compile examples/tp53_prime_edit.hx # 质粒编辑（pegRNA）
helix compile examples/tp53_knock_in.hx # HDR敲入（切割 + 捐赠者）
helix compile examples/tp53_ko_ensembl.hx # 从Ensembl解析TP53（网络）
helix validate examples/tp53_ko.hx # 解析 + 安全筛查仅
```
`compile`打印Markdown协议和（使用`-o`）写入`out/design.json`（可重复记录）和`out/protocol.md`（实验人员阅读的内容）。在[`examples/`](https://github.com/coindef/Helix/tree/main/examples)中查看所有八种模式。
## 语言
Helix规范可以用**Helix语法**（`.hx`）或**YAML**编写 — 两者都编译为相同的验证`ExperimentSpec`。
```hx
helix "TP53_KO_HEK293" {
organism: human(GRCh38)
profile: strict # 预设效率 / 离靶 / GC / 发夹默认值
target: gene(TP53) { goal: knockout; region: exon(2..4); frame: 0 }
strategy { modality: crispr_ko; enzyme: auto } # `auto` → 编译器选择（递送感知）
constraints {
on_target.min_efficiency: 0.5
off_target.max_cfd: 0.2
gc.min: 0.4 # 间隔GC窗口
guides.count: 3
avoid: [ homopolymer(>=4), self_complementary(>=8), common_variant(>=0.01) ]
}
simulate { sequence_provider: ensembl; on_target: rule_set_1; variant_source: ensembl }
deliver: rnp
validate: amplicon_seq
}
```
- **导向质量约束** — GC窗口、发夹/自补、均聚物和限制位点过滤器，每个在钻取中报告为通过/失败检查。`profile: strict | lenient | screen | quick`预设合理的默认值；您可以覆盖它们。
- **`frame: 0`**解锁上述蛋白质后果调用和保证同义HDR PAM块。
- **`variant_source: ensembl`** + `avoid: [common_variant(>=0.01)]`拒绝在种子/PAM中有常见SNP的导向。
完整语法 → [`GRAMMAR.md`](https://github.com/coindef/Helix/blob/main/helix/frontend/helix_lang/GRAMMAR.md)。
## 架构
<p align="center">
<img src="https://raw.githubusercontent.com/coindef/Helix/main/docs/architecture.svg" width="820"
alt="Helix架构 — 三层：Helix Studio（作者和审查）馈送确定性编译器（编译管道、代理和构建器、设计存储），它依赖于可注入的后端（模拟和评分）层。" />
</p>
三层：
1. **Helix Studio** — 通过**CLI**、**网页界面**或**MCP**（代理）编写和审查规范。规范是可审查的工件。
2. **确定性编译器** — 固定管道（安全 → 策略 → 目标 → 导向 → 模拟 → 约束 → 引物）加上狭义的LLM代理/构建器和带有溯源记录的设计存储。*代理仅触及规范；编译器拥有设计。*
3. **模拟和评分** — 可插入的后端为每个候选人评分。默认情况下，启发式算法离线运行；规范编辑会交换实际工具。
所有内容都通过可注入的适配器**协议**路由，因此整个脊柱都可以在离线测试，并且实际工具在相同接口后面插入。深入了解 → [`ARCHITECTURE.md`](https://github.com/coindef/Helix/blob/main/ARCHITECTURE.md)。
<a id="mcp-server"></a>
## MCP服务器 — 适用于代理的基因编辑设计
代理擅长于*编写受限规范*，而不擅长于*安全地编排原始生物信息学工具* — 正是Helix构建的分割。 因此，Helix作为一个**MCP服务器**发布：任何MCP-capable代理（Claude等）驱动编译器，但**仅限于规范→编译边界**。
```bash
helix mcp # 标准输入JSON-RPC服务器，无需额外依赖（== python3 -m helix.mcp）
```
```jsonc
// 使用MCP客户端注册
{ "mcpServers": { "helix": { "command": "helix", "args": ["mcp"] } } }
```
工具： **`helix_reference`** （语法 + 导向 + 示例）， **`helix_compile`** （规范→排名、安全筛查的设计摘要）， **`helix_resolve_gene`** （符号→序列+位置）， **`helix_list_models`** （可选后端）。MCP只是连接代理到编译器的第四种传输方式（与HTTP / 子进程 / 导入并列）。
## 后端
确定性主干使用诚实、清晰标记的启发式算法完全离线运行；每个都是一个插入点，用于在**相同协议**后面替换实际工具。
| 角色 | 内置 | 实际工具（相同接口） | 状态 |
|---|---|---|---|
| 序列 | `inline` | **`ensembl`**, **`ncbi`**, **`fallback`** (Ensembl→NCBI) | ✅ 生效 + 备用 |
| 靶向 | `heuristic_gc` | **`rule_set_1`** (Doench 2014) | ✅ 已连接 |
| 离靶 | `mock_seed` | **`cas_offinder_cfd`** (CFD; 需要基因组) | ✅ 已连接 |
| 修复结果 | `mock_indel` | **`indelphi`** (Shen 2018) | ✅ 已连接 |
| 碱基编辑结果 | `window_heuristic` | **`behive`** (Arbab 2020) | ✅ 已连接 |
| 质粒编辑结果 | `pe_heuristic` | **`pridict`** (Mathis 2023) | ✅ 已连接 |
| 结构/折叠 | `esmfold` (真实，无密钥) | **AlphaFold3 / Boltz** (`HELIX_FOLDING_BIN`) | ✅ ESMFold 生效 |
验证的核心（Doench 2014，Doench 2016 CFD）是纯粹且始终在线的；重型模型位于可注入边界后面 — 在存在基因组/工具时配置，并在否则引发明确错误，以便`mock_*`路径始终离线运行。
## 网页界面
一个交互式前端（React + TypeScript，Vite）位于FastAPI后端之上 — 编译规范并检查排名导向/pegRNAs，结果指标，可行性，安全性，溯源记录和递送建议，分为三个视图（**表格 · 3D螺旋 · Cas9复合体**）。 螺旋是**交互式的**：单击一个碱基以放置编辑，拖动以扫描它，编译器重新编译（3D→规范往返）。 **批处理**和**库**模式，**设计比较**，设计感知的**模型**页面和服务器持久的**运行历史**完善了它。
```bash
# 一条命令生成产品：构建UI一次，然后在单个源站上提供UI + API。
cd frontend && npm install && npm run build && cd ..
pip install -e '.[web]' && helix serve # 完整应用程序，访问 http://localhost:8000
```
<details>
<summary><b>高级</b> — LLM代理 · 分析循环 · 递送 · 订单导出</summary>
<br>
- **LLM代理** （可选，`ANTHROPIC_API_KEY`）— `helix author`将英文转换为`.hx`规范（由真实解析器验证，自修复错误）； `--strategy llm|rag`解析`enzyme: auto`（RAG引用文献语料库）； `helix critique`标记弱点并提出**IR验证**约束编辑； `helix refine`运行批评→重新编译直到收敛。LLM位于可注入客户端后面，完全离线测试带有假客户端。
- **设计→验证→分析循环** — `helix analyze`在扩增子读取上运行[CRISPResso2](https://github.com/pinellolab/CRISPResso2)并**将观察到的编辑与设计的预测相协调**。在UI中，*分析*卡使用纯Python调用器（无需安装）执行相同的操作。
- **现成寡核苷酸** — 每个设计导出导向克隆寡核苷酸（Golden Gate），pegRNA延伸，ssODN捐赠者和验证引物作为表格+ IDT CSV，附带粗略成本。
- **递送感知策略** — 根据载体大小和上下文推荐RNP / 质粒 / LNP / AAV，遵守单AAV限制（具有`enzyme: auto`的AAV敲除选择紧凑的SaCas9）。
- **基因数据库** — 从Ensembl / NCBI实时解析符号为其编辑窗口；**模型**页面列出每个后端的状态，显示*就绪/需要设置*。
</details>
## 许可证
[Apache-2.0](https://github.com/coindef/Helix/blob/main/LICENSE).
