archex

# archex [](https://github.com/Mathews-Tom/archex/actions/workflows/ci.yml) [](https://pypi.org/project/archex/) [](https://pypi.org/project/archex/) [](LICENSE) [](assets/archex-banner.svg) --- **验证本地代码上下文，为智能代理提供支持。** 通常，AI 编程智能代理首先打开一个文件，跟随导入，检查类型定义，然后回溯整个仓库，直到上下文窗口部分耗尽才开始真正的任务。archex 在前端执行检索和结构扩展，并返回一个排名、代币预算的上下文包，以及一份收据，记录了包含的内容、跳过的内容以及该包是否完整到足以执行。 它在本地运行，使用确定性检索和分析，不需要托管推理或 API 密钥。v0.13 版本添加了更强的基准测试信任表面、仅限于包的评估器支持和默认的 4 位 TurboQuant 矢量存储，用于本地矢量索引。 **开始：** [30 秒快速入门](#30-秒快速入门) · [MCP 和 Claude Code](#mcp-和-claude-code) · [Python API](#python-api) · [本地指标](docs/LOCAL_METRICS.md) · [兼容性矩阵](docs/CLIENT_COMPATIBILITY_MATRIX.md) · [安装信任合约](docs/INSTALLATION_TRUST_CONTRACT.md) · [安全策略](SECURITY.md) **快速链接：** [证明栏](#证明栏) · [快速路径](#快速路径) · [archex 返回的内容](#archex-返回的内容) · [按需使用](#按需使用) · [信任和操作](#信任和操作) · [测量结果](#测量结果) · [高级工作流](#高级工作流) · [安装详情](#安装详情) · [语言支持](#语言支持) · [开发](#开发) · [文档地图](#文档地图) [](assets/archex-infographic-landscape.svg) [观看讲解](assets/archex-explainer.mp4) · [打开横幅 SVG](assets/archex-banner.svg) · [打开信息图 SVG](assets/archex-infographic-landscape.svg) · [阅读测量比较](docs/ARCHEX_VS_COCOINDEX.md) ## 证明栏 | 安全信号 | 表面 | 语言覆盖率 | 公共证据 | | --- | --- | --- | --- | | 查询/侦察收据暴露新鲜度、索引修订、跳过候选人、省略边缘、完整性和下一个动作 | CLI、MCP、Python API、Docker、Claude Code 技能 | 25 个声明的语言 ID，具有明确的 `full` 和 `chunk-only` 层级 | C1 公共比较、原始 ripgrep/read 基线、仅限于包的评估器车道和 TurboQuant A/B 测量，平均矢量 `.npz` 压缩率为 7.07 倍 | archex 不要求下游代理仅信任排名。每个查询/侦察收据都解释了返回的内容、跳过的内容、新鲜度是否当前以及该包是否完整到足以执行。 ## 快速路径 | 如果您正在评估... | 从这里开始 | 为什么 | | --- | --- | --- | | 智能代理工作流 | `archex doctor`，然后 `archex scout "question" --budget 1000 --format json` | 首先检查本地信任，然后返回一个紧凑的地图、收据摘要和确切的句柄。 | | Claude Code 或 MCP | [MCP 和 Claude Code](#mcp-和-claude-code) | 标准输入输出 MCP 服务器，可选的温暖 `--watch`，附加的顶级收据和存储库内的技能，教导医生 → 侦察 → 获取。 | | Python 应用程序 | [Python API](#python-api) | 确定性 `query()`、`analyze()`、`compare()` 和带有收据的包。 | | 基准测试证明 | [测量结果](#测量结果) 和 [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) | 相同的任务 C1 报告、原始 ripgrep/read 基线、仅限于包的评估器报告、所需的信任门控和 TurboQuant 存储/召回证据。 | | 安装和客户端 | [兼容性矩阵](docs/CLIENT_COMPATIBILITY_MATRIX.md) | 客户端启动路径，用于 Claude Code、Codex、Pi、OpenCode、Cursor 和 oh-my-pi (`omp`)；默认全局/用户范围，`--dry-run` 预览。 | ## 30 秒快速入门 ```bash uv tool install archex archex doctor archex query "身份验证是如何工作的？" --format xml ``` `archex doctor` 报告本地索引、语法支持、模型缓存、MCP 注册和 `.archex/` 状态是否健康。存储库本地命令默认为当前工作目录。如果存储库尚未初始化： ```bash archex init archex index archex query "身份验证是如何工作的？" --format xml ``` ## archex 返回的内容 archex 返回一个 **上下文包和收据**，而不是答案。下游代理或模型仍然进行推理；archex 决定哪些代码、符号、依赖项和类型上下文属于提示，然后记录为什么该包是安全或不完整的。 ```xml <context query="身份验证是如何工作的？"> <structural-context> <file-tree><![CDATA[ src/auth/ middleware.py tokens.py models.py ]]></file-tree> </structural-context> <chunks> <chunk file="src/auth/middleware.py" lines="42-78" symbol="authenticate" score="0.9312" tokens="284"> <imports><![CDATA[from auth.tokens import verify_jwt]]></imports> <code><![CDATA[ def authenticate(request: Request) -> User: token = extract_bearer(request) claims = verify_jwt(token) return load_user(claims.sub) ]]></code> </chunk> </chunks> <type-definitions> <type-def file="src/auth/models.py" symbol="User" lines="10-24"><![CDATA[ @dataclass class User: ... ]]></type-def> </type-definitions> <dependencies> <internal>auth.tokens.verify_jwt</internal> <external>pyjwt</external> </dependencies> </context> ``` 该包携带排名的区块、导入上下文、引用的类型定义、依赖关系、代币计数和出处。使用 `--format json` 或 `--format markdown` 当 XML 不是正确的下游信封时。 小型收据示例： ```json { "receipt": { "freshness": "clean", "index_revision": "3d8b0c…", "token_budget": { "requested": 12000, "consumed": 6132 }, "returned_total": 12, "skipped_total": 23, "included_edges_total": 9, "omitted_edges_total": 17, "context_complete": "incomplete", "context_complete_reason": "dependency_frontier_cut", "recommended_next_action": "fetch_skipped_candidate", "returned_context": [ { "handle": "chunk:src/auth/middleware.py::authenticate#function", "file_path": "src/auth/middleware.py", "start_line": 42, "end_line": 78, "score": 0.9312 } ], "skipped_candidates": [ { "file_path": "src/auth/session.py", "reason": "below_threshold" } ] } } ``` 使用 [CONTEXT_RECEIPTS](docs/CONTEXT_RECEIPTS.md) 获取完整的字段合约。 ## 为什么 archex 不同 智能代理通常通过打开一个文件、跟随导入、检查类型定义和回溯存储库来探索存储库。这样会在真正的任务开始之前消耗上下文。archex 首先执行本地检索和结构扩展：BM25F、可选的本地矢量/SPLADE 信号、带有边缘置信度的图扩展、类型定义打包和意图路由的代币预算。 ```text 存储库 → 存储库本地索引 → 意图路由 → 检索 → 图/类型扩展 → 代币预算包 → 代理 / MCP 客户端 ``` archex 是一个选择和组装层。压缩工具可以稍后缩小最终包，但压缩的不相关上下文仍然不相关。对于矢量索引本身，v0.13 默认启用 4 位 TurboQuant 存储，当打开矢量检索时：与当前语料库上的相同测量召回率/MRR，约七倍更小的矢量工件，以及与旧的非量化 `.npz` 文件的自描述兼容性。 ## 按需使用 ### CLI ```bash archex query "缓存无效化在哪里处理？" --format xml archex scout "身份验证如何流经此存储库？" --budget 1000 --format json archex index --quantize-vectors --quantize-bits 4 --allow-remote-code archex graph export --output .archex/archgraph.json archex graph neighbors src/auth/middleware.py --graph .archex/archgraph.json --format markdown archex symbol 'symbol:src/auth/middleware.py::authenticate#function' ``` ### MCP 和 Claude Code 安装 MCP 额外组件并注册 stdio 服务器： ```bash uv tool install "archex[mcp]" ``` ```json { "mcpServers": { "archex": { "command": "archex", "args": ["mcp"] } } } ``` 安装客户端配置（默认全局/用户范围；传递 SOURCE 路径或 `--scope project` 用于存储库本地安装）。添加 `--dry-run` 以预览确切的目标和配置而不写入： ```bash archex install-client claude-code # 全局，立即写入 archex install-client claude-code --dry-run # 仅预览，无更改 archex install-client claude-code . --scope project ``` 对于温暖的本地会话，保持 MCP 进程活跃并可选地监视存储库： ```bash archex mcp --watch --watch-path . ``` archex 是 Claude Code、Codex、Cursor、OpenCode、Pi 和 oh-my-pi (`omp`) 的一流 `install-client` 目标。仅注册是不够的：具有按需工具发现的硬件仅在智能代理激活它们后才会显示注册的服务器的工具，而命名 CLI 的智能代理指导永远不会产生 MCP 调用。将即用的指导提示附加到全局或存储库特定的代理文件中，以便智能代理首先查找 MCP 工具： ```bash archex install-client omp --agent-file ~/.omp/agent/AGENTS.md ``` `archex metrics` 然后报告 CLI 与 MCP 表面分割的指标，以便您查看智能代理是否实际通过 archex 路由上下文。[兼容性矩阵](docs/CLIENT_COMPATIBILITY_MATRIX.md) 解释了注册 → 表面 → 调用区别。 存储库内的 Claude Code 技能位于 [`skills/archex/`](skills/archex/)。其 `/archex` 命令运行 `archex doctor`，在需要时初始化/索引，然后在提出更广泛的问题之前先侦察，然后在更大的包查询之前获取确切的 `symbol:` 或 `chunk:` 句柄。 确切的安装、MCP、Docker、缓存、卸载和信任语义在 [安装信任合约](docs/INSTALLATION_TRUST_CONTRACT.md) 中记录。客户端特定的配置目标和启动路径位于 [兼容性矩阵](docs/CLIENT_COMPATIBILITY_MATRIX.md) 中。 本地使用指标默认关闭。如果用户明确启用它们，`archex metrics enable`、`ARCHEX_USAGE_METRICS=on` 或持久的指标设置，archex 在 `~/.archex/usage.sqlite` 处写入一个机器本地的账本。该账本仅记录匿名的计数器：工具名称、类别、代币计数、文件计数、存储库本地随机 ID、新鲜度和索引修订。它不存储查询文本、文件路径、符号、句柄、渲染输出、提示主体、远程 URL、组织名称或存储库名称在事件行中。`archex metrics summary` 报告两个标记的节省数字：与完整文件粘贴的节省 (`tokens_saved = max(full_file_tokens - returned, 0)`，其中 `full_file_tokens` 是返回的文件的实际每个文件代币成本，而不是膨胀的块总和）和与现实的目标读取的节省（匹配的行范围加上一个小的上下文窗口 - 保守的反事实）。两个基线都来自索引，因此指标路径不重新读取任何文件也不调用任何模型。整个存储库中避免的代币被降级到节省行以下，并标记为上限/上下文数字，而不是节省。 重要边界：archex 默认情况下不附带任何遥测功能。可选的本地指标与遥测功能分开，保留在机器上，需要明确启用。详细的跟踪仍然需要一个额外的显式选择加入 `archex metrics trace enable` 或 `ARCHEX_USAGE_TRACE=on` 之上。跟踪仍然仅限于本地，并且不存储源代码或渲染输出。指标代码路径不进行任何 LLM 调用、托管上传调用或后台网络调用。 `archex metrics` 是控制表面： ```bash archex metrics enable archex metrics archex metrics export --output usage.json archex metrics delete --all archex metrics trace enable ARCHEX_USAGE_METRICS=on archex query "身份验证在哪里处理？" ``` 通过 `archex metrics trace enable` 或 `ARCHEX_USAGE_TRACE=on` 启用详细跟踪。跟踪仍然仅限于本地，并且不存储源代码或渲染输出。 ### Python API ```python from archex import query from archex.models import RepoSource bundle = query( RepoSource(local_path="."), "数据库连接池实现在哪里？", ) print(bundle.to_prompt(format="xml")) ``` `analyze()` 返回一个 `ArchProfile`；`compare()` 返回确定性的跨存储库维度比较。LangChain 和 LlamaIndex 检索器作为可选的额外组件提供。 ### Docker 两个本地优先的镜像在 CI 中构建： <details> <summary>Docker 和温暖的容器 MCP 示例</summary> ```bash # 仅 BM25，无 torch docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/mathews-tom/archex:slim archex doctor # 带有 FastEmbed 运行时完整的本地嵌入镜像 docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/mathews-tom/archex:full archex query "缓存无效化在哪里处理？" --strategy hybrid ``` 温暖的容器 MCP 模式： ```bash docker run -d --name archex-mcp -v "$PWD:/workspace" -w /workspace ghcr.io/mathews-tom/archex:slim sleep infinity docker exec -i archex-mcp archex mcp ``` 该存储库拥有 `.archex/`，因此索引在容器重启后存活并留在源代码之外。 </details> ## 信任和操作 | 表面 | 合同 | | --- | --- | | 安全策略 | 支持的版本、披露工作流、无遥测姿势、秘密处理指导以及模型远程代码策略在 [SECURITY](SECURITY.md) 中。 | | 上下文收据 | 字段合约、新鲜度/完整性语义、输出表面和基准链接在 [CONTEXT_RECEIPTS](docs/CONTEXT_RECEIPTS.md) 中。 | | 兼容性矩阵 | 测试与未经验证的客户端、确切的配置形状、启动命令和验证步骤在 [CLIENT_COMPATIBILITY_MATRIX](docs/CLIENT_COMPATIBILITY_MATRIX.md) 中。 | | 安装信任合约 | 确切的 CLI、MCP、Docker、技能、缓存、网络、新鲜度、基准和卸载语义在 [INSTALLATION_TRUST_CONTRACT](docs/INSTALLATION_TRUST_CONTRACT.md) 中。 | | `archex install-client` | 用于 Claude Code、Codex、Pi、OpenCode、Cursor 和 oh-my-pi (`omp`) 的客户端配置编写器。默认全局/用户范围；`--dry-run` 预览而不写入。 | | `archex doctor` | 索引健康状况、陈旧性、本地模型缓存存在、语法可用性分级、MCP 注册、模型安全性和 `.archex/` 磁盘使用情况的文本/JSON 诊断。 | | 存储库本地 `.archex/` | 生成状态：设置、元数据、SQLite 索引、可选向量、图工件和狗粮历史记录。保持未提交。 | | 本地使用指标 | 计算规则、隐私边界、默认关闭与选择加入行为、导出/删除控件和保留在 [LOCAL_METRICS](docs/LOCAL_METRICS.md) 中。 | ## 测量结果 公共C1基准发布了针对`archex`、`cocoindex-code` (`ccc`) 和原始`ripgrep/read`基线的外部仓库比较。它记录了冷启动、暖延迟、召回率、精确度、F1分数、token效率、所需文件召回率、遗漏所需文件率、遗漏所需任务率、所有所需文件存在率、收据准确性和bundle完成惩罚token。检查的工件包括这些置信字段；收据准确性对于历史C1运行为`n/a`，因为这些工件早于查询收据捕获。核心检索基准不进行LLM调用。 参见 [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) 获取当前发布的比较结果，以及 [检索默认决策](docs/RETRIEVAL_DEFAULT_DECISIONS.md) 获取决策轨迹。 更广泛的竞争比较可以通过 `archex benchmark headtohead competitive --input benchmarks/headtohead/results --format markdown` 获取。它按仓库/任务家族分组并聚合（无仅聚合赢家），并添加了温暖的p50/p95延迟、区域/行召回率（如果有标签）、压缩比和操作表。检查的公共工件集现在包括基准测试专用的`archex`候选通道（`archex_query_compressed`、`archex_query_efficiency_packed`）以及`archex`、`ccc`、`raw-ripgrep/read`和两个Graphify后续通道：`graphify_build_plus_query`（聚合召回率`0.70`，所需文件召回率`0.70`，冷启动`937 ms`，温暖p50/p95 `165/184 ms`）和`graphify_query_warm`（聚合召回率`0.70`，所需文件召回率`0.70`，冷启动`0 ms`，温暖p50/p95 `168/207 ms`）。Graphify被报告为图/内存层，而不是直接检索等效赢家，因此构建成本和温暖查询成本保持独立。当操作工件存在时，会出现类似Headroom的压缩通道。除非相应的检查工件存在于`benchmarks/headtohead/results/`下，否则不会发出新的公共声明。 仅bundle评估是一条单独的可选通道：`archex benchmark bundle-eval --evaluator-command ...` 给出用户提供的本地命令，只有渲染的bundle和收据JSON，然后报告仅bundle成功，并将评估器仍需要的外部文件记录下来。`archex`不提供托管的评估器调用、遥测、凭证或该通道的默认网络行为。 跨工具token效率通过`archex benchmark cross-tool`离线测量：它将`archex`用于定位任务所需文件的token与天真`grep/read`代理（整个`grep`命中文件或命中周围的`+/-K`上下文窗口）在固定所需文件召回率下进行比较，因此没有数字比较不等召回率。在检查的参考工件（[`benchmarks/cross-tool-efficiency/cross-tool-comparison.json`](benchmarks/cross-tool-efficiency/cross-tool-comparison.json)）中，限制在`archex`达到100%所需文件召回率的任务中，与天真代理相比，token减少从95.4%到99.8%每个语料库（例如`external-localization`：13,247 vs 469,836 tokens，97.2%）。它衡量`archex`在成功时的本地化成本降低，而不是它总是成功。这是一个仅基准测试的数字：它从不进入内部账本或`archex metrics summary`。 TurboQuant证据单独使用`archex_query_hybrid_quantized_4bit`与`archex_query_hybrid`进行测量：35个任务，7.07倍平均向量`.npz`压缩，6.98倍最小压缩，召回率Δ `+0.000`，MRR Δ `+0.000`，F1 Δ `+0.000`，所需文件召回率Δ `+0.000`，平均查询延迟Δ `+110 ms`。该测试通过了默认门控，因此4位TurboQuant现在是向量索引的默认存储模式。 | 通道 | 召回率 | 所需文件召回率 | 遗漏任务率 | F1分数 | token效率 | 完成后的token效率 | 暖延迟ms | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | `archex` | 0.95 | 0.95 | 0.16 | 0.66 | 0.76 | 0.74 | 408 | | `ccc` | 0.32 | 0.32 | 0.79 | 0.31 | 0.48 | 0.41 | 521 | | `raw-ripgrep/read` | 1.00 | 1.00 | 0.00 | 0.05 | 0.00 | 0.00 | 773 | ### 这对您的工作流意味着什么 - **覆盖率接近原始搜索，无需支付原始搜索token成本。** `raw-ripgrep/read`达到`1.00`所需文件召回率，但其token效率为`0.00`。`archex`在`0.95`所需文件召回率和`0.76`token效率下运行，因此返回的bundle接近详尽的文件覆盖率，而无需用每个文本匹配填充提示。 - **遗漏任务失败率与`ccc`相比大幅下降。** `archex`的遗漏任务率为`0.16`；`ccc`为`0.79`。在发布的C1运行中，这是通常返回agent需要的文件与通常需要第二次传递才能完成任务之间的差异。 - **向量存储在没有明显检索质量变化的情况下变得更小。**发布的4位TurboQuant运行报告称，平均向量`.npz`压缩率为`7.07倍`（最小`6.98倍`），召回率Δ `+0.000`，MRR Δ `+0.000`，F1 Δ `+0.000`，因此本地向量索引在该基准测试中占用磁盘空间大大减少，而没有明显的质量下降。 ## 高级工作流 ```bash # 仓库本地生命周期 archex init archex index archex status --strict archex doctor --format json # 架构和图表面 archex analyze --format markdown archex onboard archex graph export --output .archex/archgraph.json archex graph path src/archex/cli/query_cmd.py src/archex/serve/context.py --graph .archex/archgraph.json --format markdown archex impact --changed-file src/archex/serve/context.py # 基准测试和门控 archex benchmark headtohead report --input .archex/headtohead --format markdown archex benchmark run --strategy archex_query_hybrid_quantized_4bit --output .archex/e2e-quantized --allow-remote-code archex benchmark report --input .archex/e2e-quantized --baseline .archex/e2e-baseline --format markdown archex benchmark gate --input .archex/e2e --baseline .archex/e2e-baseline --warn-latency-ms 3000 archex benchmark bundle-eval --tasks-dir benchmarks/tasks --evaluator-command ./local-evaluator archex dogfood --all --baseline benchmarks/dogfood_baseline.json --format dogfood-delta ``` ## 安装详情 ```bash uv tool install archex # CLI，全局安装 uv add archex # 项目依赖 ``` <details> <summary>可选额外功能和集成</summary> ```bash # 代理集成 uv tool install "archex[mcp]" # MCP服务器 uv add "archex[langchain]" # LangChain检索器 uv add "archex[llamaindex]" # LlamaIndex检索器 uv add "archex[lsap]" # LSP类型丰富 # 本地检索额外功能 uv add "archex[vector-fast]" # FastEmbed（ONNX支持，~50MB） uv add "archex[vector-torch]" # sentence-transformers / torch uv add "archex[splade]" # SPLADE稀疏检索 uv add "archex[graph]" # Leiden图聚类 # 核心额外功能包：图、MCP、LangChain、LlamaIndex uv add "archex[all]" ``` </details> 有关完整的信任合约，包括确切的MCP JSON、Docker命令、缓存位置、网络行为和卸载步骤，请参见 [安装和信任合约](docs/INSTALLATION_TRUST_CONTRACT.md)。 ## 语言支持 | 层级 | 语言 | 提取 | | --- | --- | --- | | `full` | Python、JavaScript、TypeScript/TSX、Go、Rust、Java、Kotlin、C#、Swift | 符号、导入、图边 | | `chunk-only` | C、C++、PHP、Ruby、Scala、Lua、Bash/Shell、SQL、HTML、CSS、YAML、TOML、JSON、Markdown、Solidity | AST分块 + 检索；无符号/导入图声明 | | `unknown` | 任何其他文本文件 | 行窗口块用于BM25可见性 | 需要另一种语言？通过Python入口点注册适配器。有关扩展合约，请参见 [系统设计](docs/SYSTEM_DESIGN.md)。 ## Archex不是 - **不是聊天机器人** — 它发出上下文包；另一个代理或LLM进行解释。 - **不是托管RAG服务** — 索引和检索在本地运行，除非您明确查询远程Git URL。 - **不是向量数据库** — 向量搜索是可选的；BM25和结构信号是一流的。 - **不是LSP替代品** — 在编译器支持的类型解析至关重要的地方使用LSAP/LSP；`archex`为代理打包仓库级上下文。 - **不是提示模板库** — 输出是结构化的检索证据，而不是提示文本。 ## 开发 ```bash git clone https://github.com/Mathews-Tom/archex.git cd archex uv sync --all-extras uv run ruff check && uv run ruff format --check . uv run pyright uv run pytest ``` ## 文档地图 权威链：README → [系统设计](docs/SYSTEM_DESIGN.md) / [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) → [路线图完成记录](docs/ROADMAP.md#2026-unified-roadmap-completion) → [检索默认决策](docs/RETRIEVAL_DEFAULT_DECISIONS.md)。 - [为什么是archex](docs/WHY_ARCHEX.md) — 这个代理令牌问题解决了什么 - [系统概述](docs/OVERVIEW.md) — 当前产品概述和边界 - [系统设计](docs/SYSTEM_DESIGN.md) — 已发布的架构、图查询、侦察员、语言层级和分发表面 - [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) — 基于证据的C1比较 - [检索默认决策](docs/RETRIEVAL_DEFAULT_DECISIONS.md) — 默认策略和TurboQuant证据门控 - [上下文收据](docs/CONTEXT_RECEIPTS.md) — 收据字段合约和安全操作语义 - [本地指标](docs/LOCAL_METRICS.md) — token节省数学、隐私边界和默认关闭与可选行为 ## 许可证 Apache 2.0 — 见 [LICENSE](LICENSE)。 ## 星历史 [](https://www.star-history.com/?repos=Mathews-Tom%2Farchex&type=date&legend=top-left)