omnex

# 欧姆尼克斯 **通用、结构感知的检索 — 以极低的 token 成本。** [](https://github.com/Mathews-Tom/omnex/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](LICENSE) [](pyproject.toml) --- 欧姆尼克斯是一款适用于结构化语料库的确定性、本地优先的检索引擎 — 目前支持文档、规格和配置；未来支持代码和感知模态。它通过专用适配器摄取每种模态，将结果归一化为一种与模态无关的中间表示（IR），并在该 IR 上运行一个分层的、**与模态无关的核心**：索引、融合、沿结构边缘扩展，并将 *完整单元* 打包成一个固定的 token 预算，而不是将片段散布到提示中。 每个查询都会返回一个 **`ContextBundle`** 给模型，以及一个可审计的 **`Receipt`**，说明返回了什么、哪个层运行了、是否调用了模型、以及运行可能声称的确定性保证。无需托管推理。无需 API 密钥。无需建立向量数据库。 **开始：** [欧姆尼克斯 vs. archex](#欧姆尼克斯-vs-archex-我需要两者吗) · [层梯度](#层梯度) · [安装](#安装) · [快速开始](#快速开始-cli) · [Python API](#python-api) · [MCP 服务器](#mcp-服务器) · [测量结果](#测量结果) **快速链接：** [欧姆尼克斯返回的内容](#欧姆尼克斯返回的内容) · [为什么它与众不同](#为什么欧姆尼克斯与众不同) · [它是如何工作的](#它是如何工作的) · [确定性和收据](#确定性和收据) · [基准测试](#基准测试-自行运行) · [状态和路线图](#状态和路线图) · [与 archex 的独立性](#与-archex的独立性) · [开发](#开发) **操作：** [安装客户端](#使用-install-client-注册) · [RAG 检索器](#rag-框架-检索器) · [Docker](#docker) · [诊断](#诊断医生) · [使用指标](#使用指标) --- ## 欧姆尼克斯 vs. archex（我需要两者吗？） 欧姆尼克斯在精神上是 [**archex**](https://github.com/Mathews-Tom/archex) 的独立继承者，但两者是 **独立项目**，共享设计理念而非代码。直接回答常见问题： - **我需要两者还是只需要一个？** 只需要一个 — 按语料库选择。它们永远不会相互依赖，可以在不冲突的情况下并行安装（两者都是本地优先、确定性的，并提供 CLI 和 MCP 服务器）。欧姆尼克斯 **完全没有** archex 依赖。 - **欧姆尼克斯是否取代 archex？** **不 — 它们是互补的。** archex 是专门为代码构建的（跨多种语言的 tree-sitter 解析、深度导入/调用图）。欧姆尼克斯是 *非代码* 结构化语料库的通用底层（散文、OpenAPI/JSON-Schema 规格、配置）。欧姆尼克斯 **目前没有代码适配器**，所以它不能取代 archex 的代码功能。今天，代码适配器是一个未来的轨道（可能最终将 archex 迁移到欧姆尼克斯，但尚未构建）。 | | **archex** | **欧姆尼克斯** | | --- | --- | --- | | 范围 | 代码仓库 | 散文、结构化规格、配置（代码待定） | | 结构来源 | AST / 导入 / 调用图（tree-sitter） | 按模态适配器 → 一个共享的 IR | | 确定性 | 确定性、无需 LLM | **分层：** 字节精确底线 + 可选模型/向量通道（收据中标记） | | 输出 | ContextBundle + 收据 | `ContextBundle` + `Receipt` | | 接口 | CLI · MCP · Python · Docker | CLI · MCP · Python · Docker | | 使用场景 | 您的语料库是源代码 | 您的语料库是文档、API 规格、模式、配置 | **经验法则：** 代码 → archex；所有结构化但非代码的内容 → 欧姆尼克斯；混合商店 → 运行两者。 ## 层梯度 欧姆尼克斯解决了真正的紧张关系，而不是敷衍了事：词典检索通常会低估散文的语义搜索，因此单一配置无法同时满足 *散文 + FTS-仅 + 击败嵌入*。答案是明确的层梯度，每个层都有自己的确定性类别和诚实的胜率 — 而不是一个模糊的滑块。 | 层级 | 添加内容 | 确定性类别 | 最适合 | 声明 | 状态 | | --- | --- | --- | --- | --- | --- | | **T0** （默认底线） | FTS5/BM25F + 效率打包器 | `byte_exact`，无需 LLM，离线 | 任意模态 | 远少于完整转储的 token；无需模型；可重现；可审计 | ✅ 已发货 | | **T1** | 确定性图 **闭包** 扩展 | `byte_exact`，无需 LLM | 结构化规格/代码（ `$ref` / 外键 / 导入边） | 预算内完成引用闭包；≤ 等召回率下的块和嵌入 token | ✅ 已发货 | | **T2** | 本地嵌入通道（可选 `[embed]` 额外） | `pinned_reproducible`（模型 + 标记器 + 运行时 + 架构） | 散文 / 自然语言查询 | ≤ 等召回率下的块和嵌入 token 在散文上 | ✅ 已发货（可选） | | **T3** | 模型提取（OCR / 字幕 / 转录） | `model_versioned`（按内容哈希缓存） | 扫描 PDF / 图片 / 音频 / 视频 | 对非文本输入进行结构化检索 | 🚧 路线图 | T0 和 T1 是 **字节精确且无模型** 的。T2 是可选的，默认关闭，并记录为较弱的确定性类别 — 确定性头衔永远不会跨层蔓延。CLI 和 MCP 接口默认运行 **T0 底线**；T1 闭包和 T2 向量检索通过 Python API 选择（并且是基准测试系列锻炼的内容）。 ## 欧姆尼克斯返回的内容 欧姆尼克斯返回 **上下文，而不是答案**。下游模型仍然进行推理；欧姆尼克斯决定哪些单元属于提示中并记录为什么选择是安全的。 规格查询（`omnex query tests/fixtures/payments_openapi.json "create payment" --format markdown`）返回打包的包及其收据： ```text paths / POST /payments: { "summary": "Create a payment", "requestBody": { ... "$ref": ".../PaymentRequest" } ... } components / schemas / PaymentRequest: { ... "amount": { "$ref": ".../Money" }, "customer": { "$ref": ".../Customer" } } components / schemas / Money: { ... } ## 收据 - returned_tokens: 128 - baseline_tokens: 264 - tiers_run: T0 - model_used: False - determinism_class: byte_exact - reference_closure_complete: False - recall_basis: lexical ``` `收据` 是一个冻结值 — 相同的输入会产生字节相同的收据。其字段： | 字段 | 含义 | | --- | --- | | `returned_tokens` / `baseline_tokens` | 发出的 token 与完整转储上限 | | `tiers_run` | 此次运行的层级 | | `model_used` / `model_version` | 是否调用了嵌入/提取模型及其版本 | | `extraction_used` | 适配器本地模型提取（OCR 等）是否运行 | | `determinism_class` | `byte_exact` · `pinned_reproducible` · `model_versioned` | | `reference_closure_complete` | `True` 仅当某一层计算了引用闭包 **且** 发出了其中的每个单元（确切的集合成员资格，绝非阈值） | | `recall_basis` | `lexical` 或 `lexical_plus_vector` — 因此不会将仅限词典的运行误认为是语义运行 | | `recall_limitations` | 由 `recall_basis` 暗示的纯语言警告 | | `embedding_provenance` | 模型 / 标记器 / 运行时 / 架构 — 仅在 T2 运行中设置，`None` 在字节精确底线 | ## 为什么欧姆尼克斯与众不同 混合搜索（BM25 + 向量）在 2026 年是基本要求 — 这不是卖点。欧姆尼克斯的优势在于以下组合，旨在通过 **精度实现答案质量**，而不仅仅是通过更少的 token 来降低成本（token 价格会下降；上下文腐烂不会）： - **结构作为依赖图，而不仅仅是文本排名。** 在语料库具有硬边缘（ `$ref` 、外键、导入、调用）的地方，完成度是一种 **正确性属性** ，而不仅仅是排名偏好。检索一个 OpenAPI 操作，T1 会确定性地遍历 `$ref` 闭包 — 拉取其请求/响应模式，重复使用共享的模式 — 而不是希望相似性使所有必需的邻居浮现。 - **默认确定性，带有收据。** T0/T1 是字节精确的、离线的和可审计的。收据将检索从黑盒变成一个可检查的步骤，用于 CI 门控、监管工作流和隔离环境。 - **完整单元，绝非片段。** 打包器在预算下选择 `INCLUDE → COMPRESS → ELIDE → SKIP`，每个单元一个，并用 `protect` 标志严格保护代码块、表格和有效载荷清单不被压缩。较少、完整、针对目标的单元减少干扰。 - **零基础设施，本地优先。** 核心路径是 SQLite FTS5 + `networkx` 遍历 + 确定性打包。无需运行的服务，无需嵌入。 ## 安装 需要 **Python 3.12+**。使用 [`uv`](https://docs.astral.sh/uv/)。 ```bash # 核心（T0/T1 — 字节精确，无模型） uv tool install omnex # 带有可选的 T2 向量通道 uv tool install "omnex[embed]" # 带有 MCP 服务器界面 uv tool install "omnex[mcp]" ``` 要将欧姆尼克斯添加为项目依赖项，请使用 `uv add omnex`（带有额外功能，如 `uv add "omnex[embed]"`）。使用 `uv tool install "omnex @ git+https://github.com/Mathews-Tom/omnex"` 从源代码安装最新的未发布版本。 额外功能：`embed`（T2 本地嵌入，通过 `fastembed`）、`mcp`（MCP 标准输入/输出服务器）、`langchain` / `llamaindex`（RAG 框架检索器）、`bench`（分段和嵌入基准测试基线；拉取 `embed`）。核心安装仅拉取 `networkx`、`tiktoken` 和 `click` — 导入 `omnex` 不会加载模型、打开套接字或读取文件。 ## 快速开始（CLI） ```bash # 验证 + 汇总语料库（每个源都通过其适配器路由，如果没有适配器则失败） omnex index path/to/spec.json # → 索引 1 个文档（s）、19 个单元（s）、7 个引用（s） # 在 token 预算下查询（T0 底线；markdown 或 json） omnex query path/to/spec.json "create payment" --budget 400 --format markdown omnex query path/to/docs/ "configure TLS for the ingress" --budget 2000 --format json ``` `index` 和 `query` 接受文件或目录。输出在固定语料库、问题和预算下是确定的。 ## Python API 库是真相的源头；CLI 和 MCP 服务器是其上的薄包装。与表面不同，库 **不提供隐含的默认配置** — 每次运行都明确说明其层级。 ```python from pathlib import Path from omnex import api, KernelConfig # T1：对规范的确定性引用闭包 cfg = KernelConfig( tier="T1", bm25_profile={"title": 2.0, "breadcrumb": 1.5, "text": 1.0, "summary": 1.0}, hop_budget_by_kind={"REFERENCES": 6, "CONTAINS": 2}, confidence_decay=0.9, enable_vector_lane=False, enable_rerank=False, ) bundle, receipt = api.query_sources([Path("spec.json")], "create payment", 400, cfg) print(receipt.tiers_run) # ('T0', 'T1') print(receipt.reference_closure_complete) # True — 引用闭包中的每个单元都被发出 print(receipt.determinism_class) # 'byte_exact' print(receipt.returned_tokens, receipt.baseline_tokens) # 169 264 ``` 从顶级包导出的表面积： - `index(corpus, references=())` / `query(corpus, question, budget_tokens, config, references=()) — 在内存 IR 上操作（`Unit`/`Reference`）。 - `index_sources(sources)` / `query_sources(sources, question, budget_tokens, config)` — 先将文件/目录路径通过适配器路由到 IR。 - 类型：`ContextBundle`、`Receipt`、`KernelConfig`、`Document`、`Span`、`Unit`、`Reference`，以及 `Tier` / `DeterminismClass` / `RecallBasis` / `EmbeddingProvenance` 字面值。 对于同一个语料库的重复查询，构建内核一次并重用它。 ## MCP 服务器 安装 `[mcp]` 额外功能，然后使用 MCP 客户端注册标准输入/输出服务器： ```json { "mcpServers": { "omnex": { "command": "omnex-mcp", "args": [] } } ``` 它公开两个工具 — `index(paths)` 和 `query(corpus, question, budget=4000)` — 返回与库和 CLI 产生的相同的字节精确 T0 包和收据。MCP 模块永远不会被 `import omnex` 导入，因此核心安装不受影响；导入它而没有额外功能会大声失败。 ### 使用 `install-client` 注册 与其手动编写 JSON 配置文件，`omnex install-client <client>` 为您编写它，适用于六个客户端 — **Claude Code、Codex、Cursor、OpenCode、Pi 和 oh-my-pi（`omp`）** — 将 `omnex` 条目合并到客户端的现有配置中，而不会覆盖无关的部分： ```bash omnex install-client claude-code # 用户/全局范围（默认） omnex install-client cursor . --scope project # 仓库本地配置 omnex install-client codex --dry-run # 预览目标 + 配置，不写入任何内容 omnex install-client omp --agent-file ~/.omp/agent/AGENTS.md # 还追加代理指导 ``` `--scope` 选择用户/全局（默认）或存储库本地 `project`; Pi 和 oh-my-pi 仅限用户。 `--dry-run` 打印解析的目标和配置，不写入任何内容。 `--agent-file` 追加一个可粘贴的、幂等的指导块，以便代理访问 `index`/`query` MCP 工具，而不是仅限 CLI。 **注册不是表面化调用。** 编写配置注册服务器；一个 harness 仍然需要将其工具表面化给代理（具有按需工具发现的 harness 保持它们隐藏，直到激活），并且代理仍然需要选择它们而不是手动读取文件 — 这是 `--agent-file` 提示的内容。 ## RAG 框架检索器 欧姆尼克斯作为检索器插入现有的 RAG 堆栈中，通过额外的功能 — 核心安装程序不会拉取任何框架。构建内核一次（`index` 用于内存 IR，`index_sources` 用于文件），然后包装它；每个查询返回框架的文档类型携带欧姆尼克斯的打包块和运行的收据作为 `omnex_receipt` 下的证明。 ```python from pathlib import Path from omnex import index_sources, KernelConfig from omnex.integrations.langchain import OmnexRetriever # 需要 [langchain] 额外功能 cfg = KernelConfig( tier="T0", bm25_profile={"text": 1.0, "title": 2.0}, hop_budget_by_kind={}, confidence_decay=0.9, enable_vector_lane=False, enable_rerank=False, ) kernel = index_sources([Path("docs/")]) retriever = OmnexRetriever(kernel=kernel, config=cfg, budget_tokens=2000) docs = retriever.invoke("configure TLS for the ingress") print(docs[0].page_content, docs[0].metadata["omnex_receipt"]["determinism_class"]) ``` LlamaIndex 检索器镜像它 — `from omnex.integrations.llamaindex import OmnexLlamaRetriever` (需要 [llamaindex] 额外功能)，`retriever.retrieve(query)` 返回携带相同块和 `omnex_receipt` 证明的 `NodeWithScore` 节点。 ## Docker 两个镜像从仓库根目录发货，没有发布到注册表 — 在本地构建它们： ```bash # 精简版：仅核心 CLI（字节精确 T0/T1，无额外功能）。 docker build -f Dockerfile.slim -t omnex:slim . docker run --rm -v "$PWD:/work:ro" omnex:slim query /work/spec.json "create payment" --budget 400 # 完整版：核心 + [embed] T2 向量通道 + [mcp] 标准输入/输出服务器。 docker build -f Dockerfile.full -t omnex:full . ``` 两者都作为非特权用户运行，并在运行时读取挂载的语料库；`ENTRYPOINT` 是 `omnex`, 因此任何子命令（`query`, `index`, `doctor`, ...）都遵循镜像名称。 ### 暖容器 `omnex-mcp` 完整镜像捆绑了 `[mcp]` 额外功能，因此它可以作为容器的驻留进程运行 `omnex-mcp` 服务器。保留一个容器在会话中存活，避免每次调用都支付解释器和适配器导入成本 — 将长期运行的容器注册为 MCP 命令，而不是每次请求都生成一个新的 `omnex-mcp`： ```json { "mcpServers": { "omnex": { "command": "docker", "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/work:ro", "--entrypoint", "omnex-mcp", "omnex:full"] } } } ``` `-i` 标志保持标准输入打开，用于 MCP 标准输入/输出传输。欧姆尼克斯是无状态的（参见 [持久化模型决策](docs/system-design.md)），因此一个温暖的容器保持进程 — 而不是一个持久化的索引 — 暖：每个查询仍然通过适配器将挂载的语料库路由到 IR，没有跨会话的磁盘索引。 ## 诊断（医生） `omnex doctor` 在一个地方报告安装和操作健康状况：欧姆尼克斯的 `omnex-mcp` 服务器是否注册到您的 MCP 客户端（重用六个 `install-client` 目标 — 无重复路径知识），使用指标的账本状态，已安装的额外功能，适配器健全性，以及持久性模式（`stateless`）。 ```bash omnex doctor # 人类可读的报告 omnex doctor --format json # 机器可读的稳定模式 omnex doctor --strict # 如果任何检查结果不是“ok”，则退出并返回非零值 ``` 在设置脚本或 CI 步骤中使用 `--strict` 以快速失败，例如，没有注册客户端或缺少预期功能。 ## 使用指标 欧姆尼克斯使用 SQLite FTS5 + `networkx` 遍历 + 确定性打包。无需运行的服务，无需嵌入。 ## 依赖 欧姆尼克斯依赖于 `networkx` 和 `tiktoken` 库，以及 `click` 命令行界面库。 ## 使用指标 omnex 可以保持一个**本地-only，默认关闭**的代币节省账本 —— 无需网络，无需上传，无需查询文本、路径或符号存储。它是 **仅限 CLI**：MCP 服务器不提供指标工具，因此代理可以通过 omnex 路由检索，但永远无法读取、更改或删除您的指标状态。 ```bash omnex metrics enable # 启用（也可以通过 OMNEX_USAGE_METRICS=1 启用） omnex query spec.json "create payment" --budget 400 # 记录一个匿名事件 omnex metrics summary # 标记代币节省 + CLI 与 MCP 分割 omnex metrics summary --format json # 机器可读 omnex metrics export # 每个事件为 JSON —— 仅匿名计数器 omnex metrics delete # 清除账本（启用设置保持不变） omnex metrics trace # 单独的第二个选择；不存储源/输出 ``` 账本位于 `~/.omnex/usage.sqlite`（使用 `OMNEX_HOME` 覆盖主目录）。节省的代币来源于每个收据的 `returned_tokens` 与 `baseline_tokens` 的比较 —— 一个完整的文件粘贴基准和一个有针对性的读取反事实，整个语料库的数据被降级并标记。禁用指标（默认）时，不会创建账本文件，也不会记录任何内容。 ## 测量结果 以下所有数字均来自 [`benchmarks/results/`](benchmarks/results) 下检查的工件，由 `omnex-bench` 重新生成。代币账本是一个空格词计数（`omnex.kernel.packer.count_tokens`）；延迟与环境相关，**排除**在确定性保证之外。 ### 规格（T1 — 强保护证明） 语料库：一个包含 938 个代币的商业 OpenAPI 规格说明。每次方法的召回率保持在 **1.00**；omnex 返回确切的 `$ref` 闭包，基准检索过多以保持安全。 | 任务 | omnex T1 | 分块并嵌入 | 完整转储 | omnex F1 | 分块并嵌入 F1 | | --- | --- | --- | --- | --- | --- | | create_payment | **210** | 917 | 938 | 1.00 | 0.55 | | dispatch_shipment | **259** | 1065 | 938 | 1.00 | 0.67 | | enroll_subscriber | **191** | 1065 | 938 | 1.00 | 0.55 | | **总计** | **660** | 3047 | 2814 | — | — | omnex T1 **花费的代币约为分块并嵌入 headline 的 0.22 倍，召回率相等（1.00）**，F1 更高 —— 完整性是 **可证明的**（真实边的传递闭包），而非概率性的。p95 ≈ 9 ms。 ### 散文（T0 诚实底线，T2 竞争车道） 语料库：一个包含 489 个代币的文档集。T0 是 **词汇字节精确底线** 与完整转储上限的比较，在 omnex 实现的召回率下报告： | 任务 | omnex T0 | 完整转储 | omnex 召回率 | 是否达到完整召回率？ | | --- | --- | --- | --- | --- | | configure_tls | **82** | 489 | 0.67 | 否 —— 词汇上限 | | provision_storage | **113** | 489 | 1.00 | 是 | T0 诚实地 **落后于嵌入式**，在查询和内容词汇分散时（“使用证书保护流量”页面从未提及 *TLS*）。选择加入的 **T2 矢量车道** 在召回率为 **1.00** 时，与分块并嵌入 headline（`BAAI/bge-small-en-v1.5`，256/32 块）缩小了这一差距： | 任务 | omnex T2 | 分块并嵌入 | 完整转储 | | --- | --- | --- | --- | | configure_tls | **384** | 543 | 489 | | provision_storage | **195** | 217 | 489 | | **总计** | **579** | 760 | 978 | T2 在较少或相等的代币情况下达到分块并嵌入的召回率，但它是较弱的 `pinned_reproducible` 类别：这些计数仅在记录的模型、标记器、运行时和架构（都在收据中捕获）时才会重现。p95 ≈ 1.07 秒（模型加载）；T0 p95 ≈ 87 毫秒。 ## 工作原理 ```mermaid flowchart LR A["文档 · 规格说明 · 配置文件"] --> B["每种模态适配器"] B --> C["模态无关 IR<br/>文档 · 单元 · 引用 · 结构图"] C --> D["模态盲内核<br/>索引 → 融合 → 图形展开 → 打包"] D --> E["上下文包"] D --> F["收据"] ``` **IR 是合约**。适配器是 **唯一** 模态特定的内容；内核从不解析原始字节，从不了解模态。四种形式： - `Document` —— 内容寻址源（uri，模态，内容哈希，原始代币计数）。 - `Unit` —— 可检索/打包的原子：跨度回到源，文本，代币计数，标题，breadcrumb，`kind`（`SECTION`/`TABLE`/`OPERATION`/`SCHEMA`/…），以及 `protect`。 - `Reference` —— 类型化的，置信度加权的定向边（`CONTAINS`/`CROSS_REF`/`CITES`/`REFERENCES`/`FOREIGN_KEY`/`IMPORTS`/`CALLS`/…）。 - `StructureGraph` —— 单位和引用的 `networkx` DiGraph，推动扩展。 IR 是 **版本化的，不作为不可变** —— 预计在下一个适配器落地时会有刻意的修订。 **适配器**（`ModalityAdapter` 协议：`claims` → `ingest` → `parse` → `link` → `capabilities`）。目前已发布： - **规格适配器** —— OpenAPI / JSON-Schema → `OPERATION`/`SCHEMA`/`FIELD` 单位，具有 `REFERENCES`（`$ref`）和 `FOREIGN_KEY` 边。启用 T1 闭包。 - **散文适配器** —— Markdown / reStructuredText → `SECTION`/`PARAGRAPH`/`TABLE` 单位，具有 `CONTAINS`/`SIBLING`/`CROSS_REF`/`CITES` 边和代币感知分割。 基于模型的提取（OCR，字幕）为适配器本地 T3 通道保留 —— 默认关闭，收据记录，并在需要时 **大声失败**（一个单元标记为 `extraction=absent`，从不静默丢弃或伪造）。 **内核**（模态盲，行为由 `KernelConfig` 选择）：一个通用的 SQLite **FTS5/BM25F** 索引，涵盖 `text`/`title`/`breadcrumb`/`summary`；**RRF + 相对分数融合**，涵盖单元 ID；**图形扩展**，具有每种类型跳跃预算和置信度衰减（T1 计算确定性传递闭包）；一个可选的 **矢量车道**（T2）；以及 **打包器** —— 具有图形距离惩罚和 `INCLUDE → COMPRESS → ELIDE → SKIP` 链的每个代币相关性评分。在 T0/T1 中，`COMPRESS` 严格确定性和提取性（无模型），由测试强制执行。 ## 确定性和收据 相同的语料库 + 相同的配置 + 相同的查询 ⇒ 相同的包和字节相同的收据，在字节精确的层面上。收据是 omnex 保持 headline 诚实的方式： - T0/T1 报告 `byte_exact` 和 `model_used: False`。 - T2 报告 `pinned_reproducible` 并记录 `embedding_provenance`。 - `reference_closure_complete` 是一个确切的集合成员资格事实，从不置信度阈值。 - `recall_basis` + `recall_limitations` 以纯语言状态表示召回率仅为词汇时以及将在何处落后于嵌入式。 ## 基准测试（自己运行） ```bash # 规格系列：omnex T1 与分块并嵌入 headline（需要 [bench]/[embed] 额外） omnex-bench run --family specs --embedder bge-small --out benchmarks/results # 散文系列：omnex T0 与完整转储上限在 omnex 实现的召回率下 omnex-bench run --family prose --out benchmarks/results # 无模型下载的确定性基准线 omnex-bench run --family specs --embedder tfidf --out benchmarks/results ``` 语料库 **形状** 选择比较：单个文件语料库运行规格样式的 T1 与分块并嵌入比较；目录语料库运行散文样式的 T0 与完整转储比较。基准测试是 **离线且从不产品路径** —— 嵌入式模型是基准测试依赖项，仅在基准测试中而非 omnex 的确定性检索中。 诚实纪律融入家族：两个基准线（完整转储上限被 **降级**；固定的强分块并嵌入配置是 **headline**），固定召回率的代币，F1 和 p95。 ## 状态和路线图 **Alpha（`0.1.0`），发布到 [PyPI](https://pypi.org/project/omnex/)。** 已发布：模态无关的 IR + `StructureGraph`；规格和散文适配器；模态盲内核（FTS5/BM25F，RRF/RSF 融合，有界图扩展，T1 闭包，效率打包器）；选择加入的 T2 矢量车道；收据；规格 + 散文基准测试家族；表面和采用层 —— 库，CLI，MCP，精简/完整 Docker 镜像，LangChain/LlamaIndex 检索器，跨客户端 `install-client` 注册，本地使用指标和 `doctor` 诊断。 路线图，每个作为自己的规格说明 → 计划 → 实现周期： - **T3** 模型提取通道（OCR 适用于扫描的 PDF；字幕/转录）。 - **代码适配器**（tree-sitter → `FUNCTION`/`CLASS` 单位，`IMPORTS`/`CALLS` 边）—— 与 archex 到 omnex 迁移的缝隙。 - **混合语料库跨模态链接**（散文 ↔ 代码）。 ## 与 archex 独立 omnex 是一个原创实现。其 `src/` 和 `tests/` **不包含对 `archex` 的引用**，其依赖树不携带任何 archex 包 —— archex 被研究为一个 **参考设计**（确定性打包，结构扩展，收据）并在模态无关的 IR 上重新实现。依赖箭头从不指向代码专门化的工具。 ## 开发 ```bash git clone https://github.com/Mathews-Tom/omnex cd omnex uv sync uv run ruff check . && uv run ruff format --check . # 校验 + 格式化 uv run mypy --strict src/omnex tests # 类型 uv run pytest # 测试 ``` CI 在每次推送和 PR 上运行相同的四个门控。标准：Python 3.12，`from __future__ import annotations`，内置泛型 / `|` 联盟，`mypy --strict`。 ## 文档 **开始使用** - [安装](docs/INSTALLATION.md) —— 安装方法，额外功能，Docker，omnex 读取/写入的内容，网络行为，卸载。 - [使用](docs/USAGE.md) —— 跨 CLI，Python API，MCP 服务器和 RAG 检索器的端到端指南。 **参考** - [收据](docs/RECEIPTS.md) —— 可审计的收据合约：字段，确定性类别，召回依据。 - [本地指标](docs/LOCAL_METRICS.md) —— 默认关闭的使用账本，节省数学和隐私边界。 - [客户端兼容性](docs/CLIENT_COMPATIBILITY.md) —— `install-client` 目标，配置形状和所有六个客户端的作用域。 **设计** - [系统概述](docs/system-overview.md) —— 什么，为什么（上下文轮换，代币经济学），市场框架。 - [系统设计](docs/system-design.md) —— IR 合约，适配器协议，内核内部，层语义。 - [路线图](docs/ROADMAP.md) —— 已发布在 0.1.0 中与计划的，以及引导未来工作的原则。 **项目** - [贡献](CONTRIBUTING.md) —— 本地工作流，门控，编码标准和适配器合约。 - [安全](SECURITY.md) —— 安全姿态和如何报告漏洞。 - [变更日志](CHANGELOG.md) —— 发布历史。 ## 许可证 [Apache License 2.0](LICENSE)。