内容
# Helix 上下文
[](https://opensource.org/licenses/Apache-2.0)
[](https://pypi.org/project/helix-context/)
[](https://www.python.org/downloads/)
[](tests/)
[](docs/architecture/PIPELINE_LANES.md)
[](https://mbachaud.substack.com/p/agentome)
> 针对大型语言模型代理的坐标索引引擎。在检索路径上无需进行任何大型语言模型调用，即可将代码库检索、权衡和压缩到上下文窗口中。
---
## 验证（30 秒）
**正在进行的基准测试** - 禁用压缩器（默认无LLM配置），N=15查询形状，2026年5月：
| 指标 | tokens | vs 标准RAG（top-5 @ 1500） |
|--------|--------|-------------------------------|
| 中位数 | 2,757 | **2.9×** 更少 tokens |
| 最佳（聚焦查询） | 1,410 | **5.7×** |
| 最差（广泛的12-doc） | 3,755 | **2.1×** |
启用可选的压缩器（Claude Haiku splice），中位数提高到约5×。在多轮会话中，会话传递寄存器省略已见文档 - 在会话中重复检索时观察到 **37× 减少** 。
重现器：`python benchmarks/bench_rag_vs_sike_tokens.py` 对比您自己的基因库。
**代理合约**：每个 `/context` 响应携带 `know { found, confidence }` （有根据 - 您可能回答）或 `miss { reason, escalate_to }` （未找到 - 不要从基因库回答）。过期结果通过新鲜度门户降级为 `miss(reason="stale"|"cold"|"superseded")`。
## 入门（60 秒）
```bash
# 1. 安装
pip install helix-context
python -m spacy download en_core_web_sm
# 2. 导入代码库
helix ingest path/to/your/project/ --recursive
# 3. 查询
helix query "如何工作的拼接步骤？"
# 4. 或启动IDE集成的代理
helix-server # 绑定到 127.0.0.1:11437
```
有关额外矩阵、BGE-M3反向填充和托盘设置的详细信息，请参阅：[docs/SETUP.md](docs/SETUP.md)。
## 代理接口
通过 Helix 的三种驱动方式 - 相同的检索基元，相同的JSON形状：
| 接口 | 最适合 | 示例 |
|---------|----------|---------|
| **CLI** | 脚本、CI、冷启动代理 | `helix query "..." --json` |
| **MCP** | Claude Code, Cursor, Claude Desktop | 添加到 `settings.json` |
| **HTTP代理** | Continue IDE, `OPENAI_BASE_URL` 重定向 | `POST /context` |
```bash
# CLI - 无服务器，无守护进程，可通过子进程驱动
helix query "拼接步骤是做什么的？" --json
helix packet "编辑拼接步骤" --task-type edit --json
helix gene get abc123 --json
helix neighbors "拼接步骤" --k 10 --json
helix refresh-targets "编辑拼接步骤" --json
helix status
helix diag corpus
```
完整的CLI参考：[`docs/clients/cli.md`](docs/clients/cli.md）。
MCP工具模式：[`docs/api/mcp-tools.md`](docs/api/mcp-tools.md)。
## 流水线（2分钟）
每回合七个阶段，除可选的拼接外均为无LLM：
```
查询
│
▼
┌──────────────┐
│ 0. 分类 │ 基于规则：解码器模式 + 装配上限
└──────┬───────┘
▼
┌──────────────┐
│ 1. 提取 │ 启发式关键词 + 实体提取
└──────┬───────┘
▼
┌──────────────┐ FTS5 BM25 + BGE-M3 密集（1024维）+ 标签
│ 2. 检索 │ + 同义词扩展 + 共激活 + SR
│ │ 通过RRF或加法融合排名
└──────┬───────┘
▼
┌──────────────┐
│ 3. 重新排名 │ CPU分类器分数（可选）
└──────┬───────┘
▼
┌──────────────┐
│ 4. 拼接 │ 头部空间压缩（CPU）或LLM压缩器
└──────┬───────┘
▼
┌──────────────┐ token预算 + 易读性头部（触发层，
│ 5. 装配 │ 置信度 ◆/◇/⬦，压缩比率）+
│ + 阶段 7 │ 新鲜度门户（过期/冷/取代 → 未命中）
└──────┬───────┘ + 会话传递（省略已见文档）
▼
┌──────────────┐
│ 6. 持久化 │ 查询+响应 → 知识存储（后台）
└──────┘───────┘
▼
知道 { } 或 未命中 { }
```
- **知道/未命中合约**：`知道` 表示上下文有根据，代理可以回答。`未命中` 表示不要从基因库中回答 - 通过 `escalate_to` 工具升级或从 `refresh_targets` 重新获取。
- **调用者模型类**：`/context` 接受 `caller_model_class: "generic" | "small_moe" | "frontier"` 以选择渲染分支（排序、装配上限、解码器模式）。参见 [docs/api/context-endpoint.md §7](docs/api/context-endpoint.md)。
<details>
<summary><strong>配置（helix.toml中的17个部分）</strong></summary>
| 部分 | 关键设置 |
|---------|-------------|
| `[ribosome]` | `enabled`, `backend` (`"none"` / `"litellm"` / `"claude"` / `"deberta"`), query_expansion |
| `[hardware]` | 设备自动检测（CUDA → ROCm → MPS → CPU） |
| `[budget]` | `expression_tokens` （7k 默认），`max_genes_per_turn`，splice_aggressiveness，`legibility_enabled`，`session_delivery_enabled` |
| `[session]` | 合成会话窗口，默认 party_id |
| `[genome]` | `path` (`genomes/main/genome.db`)，compact_interval，replicas |
| `[server]` | host，port，upstream |
| `[headroom]` | 可选的 Headroom 代理生命周期 |
| `[ingestion]` | `backend` (`"cpu"` / `"ollama"`)，splade_enabled，entity_graph |
| `[context]` | 冷层检索：enabled，k，min_cosine |
| `[cymatics]` | 频域评分，harmonic_links，distance_metric |
| `[classifier]` | 基于规则的查询分类阈值 |
| `[retrieval]` | `fusion_mode` （默认 `"rrf"` / 旧版 `"additive"`），SR，ray_trace_theta，seeded_edges |
| `[plr]` | 分段线性重新排名模型 |
| `[know]` | 知道/未命中校准：emit_floor，betas，s_ref，g_ref，stale_after_days |
| `[mem_sync]` | 自动内存 → helix 同步：watch_dirs，interval |
| `[synonyms]` | 查询扩展映射（例如，“缓存” → [“redis”，“ttl”]） |
| `[abstain]` | 低置信度拒绝阈值 |
完整参考：[docs/config-reference.md](docs/config-reference.md)。
</details>
<details>
<summary><strong>完整端点参考</strong></summary>
**核心检索：**
| 端点 | 目的 |
|----------|---------|
| `POST /context` | 知道/未命中 + 表达上下文（主要） |
| `POST /context/packet` | 代理安全包：验证 / 过时风险 / 刷新目标 |
| `POST /context/refresh-plan` | 仅刷新目标（重新读取计划） |
| `POST /fingerprint` | 导航优先载荷（分数，无正文） |
| `GET /context/expand` | 从 gene_id 开始的 1 跳邻居 |
| `POST /v1/chat/completions` | OpenAI 兼容代理 |
**导入 + 维护：**
| 端点 | 目的 |
|----------|---------|
| `POST /ingest` | 将内容添加到知识存储 |
| `POST /consolidate` | 从源指纹重写过时文档 |
| `POST /admin/refresh` | 强制检索层刷新 |
| `POST /admin/vacuum` | 回收 SQLite 页面 |
| `POST /admin/swap-db` | 在不停机的情况下热交换 .db 文件 |
**身份 + 会话：**
| 端点 | 目的 |
|----------|---------|
| `POST /sessions/register` | 注册代理参与者 |
| `GET /sessions` | 列出已注册参与者 |
| `GET /session/{id}/manifest` | 会话传递日志 |
| `POST /hitl/emit` | 记录 HITL 暂停事件 |
**诊断：**
| 端点 | 目的 |
|----------|---------|
| `GET /stats` | 知识库指标 + 压缩比率 |
| `GET /health` | 模型，文档计数，校准来源 |
| `GET /genes/{gene_id}` | 单个文档详情 |
| `GET /debug/resonance` | 层激活配置文件 |
| `GET /metrics/tokens` | token 使用计数器 |
完整模式：[docs/api/endpoints.md](docs/api/endpoints.md)。
</details>
<details>
<summary><strong>软件包结构（15个软件包，PR #90后）</strong></summary>
| 软件包 | 目的 |
|---------|---------|
| `adapters/` | 缓存，DAL，外部检索协议 |
| `backends/` | 压缩器，BGE-M3编解码器，DeBERTa，NLI，SEMA，SPLADE |
| `cli/` | `helix` CLI：查询，数据包，基因，邻居，导入，诊断，配置，状态 |
| `encoding/` | 分块，片段，易读性头部，Headroom桥 |
| `identity/` | CWoLa日志，会话传递，注册，来源，声明 |
| `pipeline/` | 层逻辑，阶段助手 |
| `retrieval/` | 扩展，新鲜度，RRF/加法融合，PLR，意图路由器，SR，种子边，查询分类器 |
| `scoring/` | Cymatics，了解-校准，了解-决策，射线追踪，TCM |
| `server/` | FastAPI应用工厂 + 路由模块（上下文，导入，注册，管理） |
| `storage/` | DDL，索引，共激活图 |
| `telemetry/` | OTel指标，直方图仪表盘 |
| `vault/` | Obsidian保险库导出（诊断跟踪） |
| `launcher/` | 系统托盘监视器 |
| `mcp/` | MCP工具界面，用于Claude Code / Desktop |
| `integrations/` | ScoreRift桥 |
后兼容性垫片：`genome.py`，`ribosome.py`，`server.py`，`replication.py`，`hgt.py` 从新位置重新导出。词典：[docs/ROSETTA.md](docs/ROSETTA.md)。
</details>
## IDE + MCP 集成
<details>
<summary><strong>MCP 设置（Claude Code / Cursor / Claude Desktop）</strong></summary>
```json
{
"mcpServers": {
"helix-context": {
"command": "python",
"args": ["-m", "helix_context.mcp_server"],
"cwd": "/absolute/path/to/your/project",
"env": { "HELIX_MCP_URL": "http://127.0.0.1:11437" }
}
}
}
```
</details>
<details>
<summary><strong>继续 IDE</strong></summary>
```yaml
models:
- name: Helix (Local)
provider: openai
model: gemma3:e4b
apiBase: http://127.0.0.1:11437/v1
apiKey: EMPTY
roles: [chat]
defaultCompletionOptions:
contextLength: 128000
maxTokens: 4096
```
</details>
<details>
<summary><strong>OpenAI 兼容代理（零代码更改）</strong></summary>
```bash
OPENAI_BASE_URL=http://localhost:11437/v1 your-app
```
</details>
## 知识存储管理
```toml
[genome]
path = "genomes/main/genome.db" # 相对 helix 运行目录
```
备份（安全运行时 - WAL 模式）：
```bash
cp genomes/main/genome.db backups/genome-$(date +%Y%m%d).db
```
BGE-M3 反向填充（一次性，安装后）：
```bash
python scripts/backfill_bgem3_v2.py genomes/main/genome.db
```
## 可观察性
```powershell
scripts\setup-grafana-telem.ps1 # Windows
scripts/setup-grafana-telem.sh # Linux / macOS
```
仪表盘：<http://localhost:3000/d/helix-overview>。
完整界面：[docs/architecture/OBSERVABILITY.md](docs/architecture/OBSERVABILITY.md)。
## 注意事项
- **知识存储路径** 是 `genomes/main/genome.db` （不是项目根目录）。删除后重新开始。
- **BGE-M3 反向填充** 是一次性安装后操作 - `embedding_dense_v2 IS NULL` 直到运行 `scripts/backfill_bgem3_v2.py`。没有它，检索率很低。
- **融合模式** 默认 `"additive"` （后兼容）。在运行 `scripts/calibrate_thresholds.py` 后切换到 `"rrf"`。
- **会话传递** （`session_delivery_enabled = true`）跟踪每个会话的传递文档，省略重复项。~40% token 节省多轮。对话。 在 `/context` 正文中传递 `ignore_delivered: true` 进行基准测试。
- **知道/未命中合约** 需要代理提示片段被遵守 - 没有它，边界模型会捏造。导入 `helix_context.agent_prompt.full_fragment()`。
- **命名词典**：生物学术语（基因，基因组，核糖体）具有规范的软件等价物（文档，知识存储，压缩器）。两者在代码中都有效；新代码使用软件术语。参见 [docs/ROSETTA.md](docs/ROSETTA.md)。
## 测试
```bash
python -m pytest tests/ -m "not live" -v # ~2,750 测试，无外部服务
```
## 文档
| 开始这里 | 更深入 |
|-----------|-----------|
| [安装指南](docs/SETUP.md) | [流水线通道](docs/architecture/PIPELINE_LANES.md) |
| [故障排除](docs/TROUBLESHOOTING.md) | [检索维度](docs/architecture/DIMENSIONS.md) |
| [`/context` API](docs/api/context-endpoint.md) | [知识图](docs/architecture/KNOWLEDGE_GRAPH.md) |
| [配置参考](docs/config-reference.md) | [会话注册](docs/architecture/SESSION_REGISTRY.md) |
| [代理 SDK 片段](docs/agent-sdk-fragment.md) | [可观察性](docs/architecture/OBSERVABILITY.md) |
| [操作员运行手册](docs/operator-runbooks.md) | [启动器架构](docs/architecture/LAUNCHER.md) |
| [密集导入 ≤12 GB VRAM](docs/operations/DENSE_VRAM.md) | |
## 致谢
构建于：[spaCy](https://spacy.io/) NER · [Howard 2005](https://doi.org/10.1037/0033-295X.112.3.559) TCM · [Stachenfeld 2017](https://www.nature.com/articles/nn.4650) SR · SQLite FTS5 BM25 · [BGE-M3](https://huggingface.co/BAAI/bge-m3) · [Kompress](https://huggingface.co/chopratejas/kompress-base) · [Headroom](https://github.com/chopratejas/headroom)
## 许可证
[Apache-2.0](LICENSE). 查看 [NOTICE](NOTICE) 以获取第三方属性。
