open-context-engine 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,7 @@
     <a href="docs/BENCHMARKS.md#engineering-validation"><img src="https://img.shields.io/badge/verified_tests-107-23875b?style=flat-square" alt="107 verified tests"></a>
     <a href="docs/QUICKSTART.md"><img src="https://img.shields.io/badge/MCP-stdio-193c34?style=flat-square" alt="MCP over stdio"></a>
   </p>
-  <p><a href="#quick-start">Quick start</a> · <a href="docs/BENCHMARKS.md">Benchmarks</a> · <a href="docs/QUICKSTART.md">MCP setup</a></p>
+  <p><a href="#quick-start">Quick start</a> · <a href="docs/BENCHMARKS.md">Benchmarks</a> · <a href="docs/QUICKSTART.md">MCP setup</a> · <strong>English</strong> | <a href="README.zh-CN.md">简体中文</a></p>
 </div>
 
 OpenContextEngine is a **self-hostable code context engine for AI coding agents**. Connect it to your agent through MCP to help it explore an unfamiliar codebase, locate implementations, and find the related code needed for a fix or feature.
@@ -37,9 +37,9 @@ Measured with the optional batch rerank API. 40 source-derived tasks, each asked
 
 Requires **macOS or Linux**, Node.js 22.14+, Python 3.10+, Git, and configured embedding/reranking services. Go repositories also need Go 1.22+.
 
-**Preparing the first npm release; not yet published.** Get the installation archive from the maintainer, then expand your client's guide. Model settings are shared across clients on the same machine.
+Install from npm, then expand your client's guide. Model settings are shared across clients on the same machine.
 
-<details>
+<details open>
 <summary><strong>Codex — install, connect, and search</strong></summary>
 
 **1. Install the CLI**
@@ -47,7 +47,7 @@ Requires **macOS or Linux**, Node.js 22.14+, Python 3.10+, Git, and configured e
 With Codex CLI already installed, run:
 
 ```sh
-npm install -g /path/to/open-context-engine-0.1.0.tgz
+npm install -g open-context-engine
 ```
 
 **2. Configure your models**
@@ -80,8 +80,6 @@ Ask:
 
 Codex supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Codex to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.
 
-[Codex MCP reference](https://developers.openai.com/codex/mcp)
-
 </details>
 
 <details>
@@ -92,7 +90,7 @@ Codex supplies the project's absolute path as `directory_path`. The first reques
 With Claude Code already installed, run:
 
 ```sh
-npm install -g /path/to/open-context-engine-0.1.0.tgz
+npm install -g open-context-engine
 ```
 
 **2. Configure your models**
@@ -124,8 +122,6 @@ Run `/mcp` to check the connection, then ask:
 
 Claude supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Claude to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.
 
-[Claude Code MCP reference](https://code.claude.com/docs/en/mcp)
-
 </details>
 
 <details>
@@ -148,30 +144,16 @@ Your agent supplies the current project's absolute path as `directory_path`. To
 
 </details>
 
-<details>
-<summary>Run from source or build an internal package</summary>
-
-```sh
-git clone https://github.com/AnnaSuSu/OpenContextEngine.git
-cd OpenContextEngine
-npm ci
-node bin/opencontextengine.mjs setup
-# Build an installable archive for internal testers:
-npm pack
-```
-
-Use the absolute Node and CLI paths printed by setup. [Client-specific configuration →](docs/QUICKSTART.md#client-setup-notes)
-
-</details>
-
 [Model configuration, troubleshooting, and update behavior →](docs/QUICKSTART.md)
 
-Once published, install with `npm install -g open-context-engine`. Until then, use the archive above. [Release checklist](docs/RELEASING.md).
-
 ## Explore
 
-[Benchmark report](docs/BENCHMARKS.md) · [Raw evaluations](docs/eval/results) · [Retrieval engine](src/retrieval) · [Logo assets](assets/brand)
+[Benchmark report](docs/BENCHMARKS.md) · [Raw evaluations](docs/eval/results) · [Retrieval engine](src/retrieval)
 
 ## License
 
 [MIT](LICENSE) © 2026 AnnaSuSu.
+
+## Acknowledgments
+
+Thanks to the [LINUX DO](https://linux.do/) community.

package/README.zh-CN.md

@@ -0,0 +1,159 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo-lockup-dark.svg">
+    <img src="assets/brand/logo-lockup.svg" alt="OpenContextEngine" width="660">
+  </picture>
+  <p><strong>为 AI 编程助手提供精准的代码上下文。</strong></p>
+  <p>跨文件查找相关代码，追踪代码之间的联系，让助手的回答有据可查。</p>
+  <p>
+    <a href="docs/BENCHMARKS.md#seven-method-comparison"><img src="https://img.shields.io/badge/dev_evidence_coverage-94.79%25-23875b?style=flat-square" alt="开发集证据覆盖率：94.79%"></a>
+    <a href="docs/BENCHMARKS.md#seven-method-comparison"><img src="https://img.shields.io/badge/median_retrieval-1.73_s-23875b?style=flat-square" alt="检索耗时中位数：1.73 秒"></a>
+    <a href="docs/BENCHMARKS.md#engineering-validation"><img src="https://img.shields.io/badge/verified_tests-107-23875b?style=flat-square" alt="107 项已验证测试"></a>
+    <a href="docs/QUICKSTART.md"><img src="https://img.shields.io/badge/MCP-stdio-193c34?style=flat-square" alt="通过 stdio 接入 MCP"></a>
+  </p>
+  <p><a href="#快速开始">快速开始</a> · <a href="docs/BENCHMARKS.md">评测报告</a> · <a href="docs/QUICKSTART.md">MCP 配置</a> · <a href="README.md">English</a> | <strong>简体中文</strong></p>
+</div>
+
+OpenContextEngine 是一个**可自行部署、面向 AI 编程助手的代码上下文引擎**。通过 MCP 接入后，助手可以借助它理解陌生代码库、定位实现，以及查找修复问题或开发功能所需的相关代码。
+
+它为你的工作目录建立索引，并跟随已保存的代码变化自动更新。面对自然语言任务，它结合语义检索、关键词检索、代码关系和重排，在指定的上下文预算内返回相关源码片段、文件路径和行号。
+
+## 为什么选择 OpenContextEngine
+
+- **用自然语言查代码。** 描述你要找的行为，检索其实现及跨文件的相关代码。
+- **理解代码结构。** 支持 Python、TypeScript、JavaScript 和 Go 的结构分析，其他语言、配置文件和脚本使用文本检索保底。
+- **索引跟随代码更新。** 保存修改、删除文件和切换分支后自动同步。复用未变化的向量，更新未完成时保留完整的旧索引。
+- **通过 MCP 跨项目使用。** 助手传入项目路径，按需启动并复用索引。`search_code` 检索代码证据，`index_status` 查看同步状态。
+
+## 评测结果
+
+![所需证据覆盖率与实测查询耗时](assets/benchmarks/method-comparison.svg)
+
+**所需证据覆盖率 94.79% · 检索耗时中位数 1.73 秒 · 80 次查询中有 69 次覆盖全部所需证据。** 七种引擎、四个仓库，统一采用 4,000 token 的输出预算。在这组内部开发评测中，OpenContextEngine 保留的所需证据最多。
+
+评测使用可选的批量重排接口。共 40 个基于源码设计的任务，每个任务分别用中文和英文提问。覆盖率衡量源码证据的保留情况，不代表编程助手完成任务的成功率。开源工具记录原生检索耗时，ACE 记录 SDK 客户端调用耗时。[完整对比、配置和逐条查询结果 →](docs/eval/METHOD_COMPARISON.md)
+
+## 快速开始
+
+需要 **macOS 或 Linux**、Node.js 22.14+、Python 3.10+、Git，以及已配置好的向量和重排服务。分析 Go 仓库还需要 Go 1.22+。
+
+通过 npm 安装，展开你所用客户端的教程即可。同一台机器、同一用户下的多个客户端可以共用模型配置。下方链接的详细技术文档目前为英文。
+
+<details open>
+<summary><strong>Codex：安装、接入与搜索</strong></summary>
+
+**1. 安装 CLI**
+
+已安装 Codex CLI 后，执行：
+
+```sh
+npm install -g open-context-engine
+```
+
+**2. 配置模型接口**
+
+```sh
+open-context-engine setup
+```
+
+依次填写向量和重排服务的基础地址、API Key、模型名，以及向量维度。安装向导会自动安装隔离的 Python 依赖并保存配置。默认重排使用普通 `/rerank` 接口。[接口填写示例 →](docs/QUICKSTART.md#2-shared-model-configuration)
+
+**3. 添加 MCP 服务**
+
+```sh
+codex mcp add open-context-engine -- open-context-engine mcp
+codex mcp get open-context-engine
+```
+
+第二条命令用于检查已保存的配置。以上命令要求客户端能通过 `PATH` 找到 `open-context-engine`。桌面端或源码安装请参考[绝对路径配置](docs/QUICKSTART.md#client-setup-notes)。添加后，重启正在运行的 Codex 客户端。
+
+**4. 搜索项目代码**
+
+```sh
+cd /path/to/your-project
+codex
+```
+
+向 Codex 提问：
+
+> 使用 open-context-engine 的 search_code 工具，解释当前项目的核心功能，并指出主要入口、相关文件路径和行号。
+
+Codex 会通过 `directory_path` 传入项目的绝对路径。首次请求会启动索引；如果还在构建，让 Codex 调用 `index_status` 检查进度，待就绪后重试。后续搜索复用索引，保存代码后自动更新。
+
+</details>
+
+<details>
+<summary><strong>Claude Code：安装、接入与搜索</strong></summary>
+
+**1. 安装 CLI**
+
+已安装 Claude Code 后，执行：
+
+```sh
+npm install -g open-context-engine
+```
+
+**2. 配置模型接口**
+
+```sh
+open-context-engine setup
+```
+
+依次填写向量和重排服务的基础地址、API Key、模型名，以及向量维度。安装向导会自动安装隔离的 Python 依赖并保存配置。如果已经为 Codex 完成配置，可以跳过这一步，直接复用。[接口填写示例 →](docs/QUICKSTART.md#2-shared-model-configuration)
+
+**3. 添加 MCP 服务**
+
+```sh
+claude mcp add --transport stdio --scope user open-context-engine -- open-context-engine mcp
+```
+
+`--scope user` 让服务在你的各个项目中都可用。如果需要团队共用的项目级配置，在该项目目录运行命令，并将 `--scope user` 改为 `--scope project`。以上命令要求客户端能通过 `PATH` 找到 `open-context-engine`；绝对路径写法见[客户端配置说明](docs/QUICKSTART.md#client-setup-notes)。添加后，重启正在运行的 Claude Code 会话。
+
+**4. 搜索项目代码**
+
+```sh
+cd /path/to/your-project
+claude
+```
+
+输入 `/mcp` 检查连接，然后提问：
+
+> 使用 open-context-engine 的 search_code 工具，解释当前项目的核心功能，并指出主要入口、相关文件路径和行号。
+
+Claude 会通过 `directory_path` 传入项目的绝对路径。首次请求会启动索引；如果还在构建，让 Claude 调用 `index_status` 检查进度，待就绪后重试。后续搜索复用索引，保存代码后自动更新。
+
+</details>
+
+<details>
+<summary>其他 MCP 客户端</summary>
+
+[安装并完成初始化](docs/QUICKSTART.md#1-install)后，运行 `open-context-engine mcp-config`，将输出配置转换为客户端支持的格式。对于接受 `mcpServers` JSON 且能通过 `PATH` 找到已安装命令的客户端，可以使用：
+
+```json
+{
+  "mcpServers": {
+    "open-context-engine": {
+      "command": "open-context-engine",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+助手通过 `directory_path` 传入当前项目的绝对路径。如果只搜索固定项目，在 `args` 中追加 `"--root", "/absolute/path/to/your-repository"`。
+
+</details>
+
+[模型配置、问题排查和索引更新机制 →](docs/QUICKSTART.md)
+
+## 进一步了解
+
+[评测报告](docs/BENCHMARKS.md) · [原始评测数据](docs/eval/results) · [检索引擎源码](src/retrieval)
+
+## 许可证
+
+[MIT](LICENSE) © 2026 AnnaSuSu。
+
+## 致谢
+
+感谢 [LINUX DO](https://linux.do/) 社区。

package/docs/QUICKSTART.md

@@ -6,10 +6,10 @@ OpenContextEngine runs a local repository index and calls configured model servi
 
 Requires Node.js 22.14+, Python 3.10+, and Git. Go source analysis also needs Go 1.22+ on `PATH`, or an explicit `OCE_GO_BINARY`.
 
-**First npm release in preparation; not yet published.** Install the archive supplied by the maintainer:
+Install the package from npm:
 
 ```sh
-npm install -g /path/to/open-context-engine-0.1.0.tgz
+npm install -g open-context-engine
 open-context-engine setup
 ```
 
@@ -24,7 +24,7 @@ npm ci
 node bin/opencontextengine.mjs setup
 ```
 
-After the first npm release, install with `npm install -g open-context-engine`, then run `open-context-engine setup`. Maintainers can build an archive with `npm pack`; see the [release checklist](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/RELEASING.md).
+For internal builds, maintainers can create an archive with `npm pack` and install it with `npm install -g /path/to/open-context-engine-0.1.1.tgz`. See the [release checklist](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/RELEASING.md).
 
 The CLI and package are named `open-context-engine`. The previous `opencontextengine` command remains an alias. Existing configuration and cache directories keep their paths, so saved keys and indexes are reused.
 
@@ -40,14 +40,16 @@ For automation, set the following environment variables and run `open-context-en
 EMBEDDING_BASE_URL=https://your-embedding-service.example/v1
 EMBEDDING_API_KEY=your-embedding-key
 EMBEDDING_MODEL=Qwen3-Embedding-4B
-OCE_EMBEDDING_DIMENSIONS=1024
+# Match the actual output size of your embedding endpoint.
+OCE_EMBEDDING_DIMENSIONS=2560
 
 RERANK_BASE_URL=https://your-reranker-service.example/v1
 RERANK_API_KEY=your-reranker-key
 RERANK_MODEL=Qwen3-Reranker-4B
-OCE_RERANK_API=rerank
 ```
 
+The setup prompt initially suggests `1024` dimensions; replace it with your endpoint's actual output size. The example above uses `2560`.
+
 The embedding service must implement `POST /v1/embeddings`. By default, the reranker uses the ordinary `/rerank` API: requests contain `model`, `query`, `documents`, and `top_n`; responses must return every requested document in `results`, with its original `index` and a finite `relevance_score` between 0 and 1. Results may arrive in relevance order. Set the reranker base URL to the part before `/rerank`: for example, `https://provider.example/v1`, `/v2`, or `https://provider.example` for an unversioned endpoint.
 
 HTTPS is the default. For an explicitly trusted remote HTTP deployment, set `OCE_ALLOW_HTTP=1` before running `open-context-engine setup`; setup saves this choice in the shared configuration. HTTP transmits API keys and source text without encryption. Local model endpoints remain prohibited. Set `OCE_EMBEDDING_DIMENSIONS` to the service's actual output size (for example, `2560`); changing the provider or dimensions creates a new index generation and does not mix incompatible cached vectors.
@@ -71,11 +73,11 @@ Then start the CLI with these overrides, or save them with `setup --non-interact
 ```dotenv
 EMBEDDING_SSH_TUNNEL_URL=http://127.0.0.1:43079/v1
 EMBEDDING_SSH_REMOTE=operator@model-host.example:22
-RERANK_SSH_TUNNEL_URL=http://127.0.0.1:43078
+RERANK_SSH_TUNNEL_URL=http://127.0.0.1:43078/v1
 RERANK_SSH_REMOTE=operator@model-host.example:22
 ```
 
-The rerank tunnel must preserve the configured base URL's path prefix (for example, `/v1` if required). Keep the SSH process running while using MCP. The CLI does not create SSH sessions or store SSH passwords, and a disconnected tunnel surfaces an error instead of falling back to public HTTP. Models continue to run on the remote server.
+The rerank tunnel must preserve the configured base URL's path prefix. The example above matches `RERANK_BASE_URL=https://your-reranker-service.example/v1`; if your provider uses an unversioned `/rerank` endpoint, omit `/v1` from both base URLs. Keep the SSH process running while using MCP. The CLI does not create SSH sessions or store SSH passwords, and a disconnected tunnel surfaces an error instead of falling back to public HTTP. Models continue to run on the remote server.
 
 ## 3. Add the MCP server
 
@@ -144,7 +146,7 @@ Client references: [Codex MCP](https://developers.openai.com/codex/mcp) · [Clau
 
 ## Updates & storage
 
-Saved files are checked every second by default, with a 300 ms debounce. New files, deletions, renames, and branch changes update the index automatically. Embeddings are reused by model identity and actual input content. Structural analysis conservatively refreshes the affected language group to update references in unchanged files.
+Saved files are checked every second by default (`OCE_POLL_SECONDS=1`), with a 300 ms debounce (`OCE_DEBOUNCE_SECONDS=0.3`). New files, deletions, renames, and branch changes update the index automatically. Embeddings are reused by model identity and actual input content. Structural analysis conservatively refreshes the affected language group to update references in unchanged files.
 
 Search actively checks source hashes before retrieval and again before returning. It waits up to 30 seconds for synchronization (`freshnessWaitMs`, maximum 120 seconds). Failed updates, timeouts, or edits during retrieval produce explicit errors. Unsaved editor buffers are not indexed.
 
@@ -152,6 +154,8 @@ State is stored in `~/.cache/opencontextengine/<repository-path-hash>/`. Overrid
 
 When model weights change under the same name, increment `OCE_EMBEDDING_REVISION`. A different provider, model name, or dimension count also invalidates vector reuse. Other models need separate compatibility and quality validation.
 
+Optional Go type analysis can be enabled with `OCE_LANGUAGE_OPTIONS='{"go":{"mode":"types"}}'`; the default uses syntax-based analysis. `OCE_PYTHON` selects an existing Python environment with the required dependencies; normal CLI installations use the runtime created by setup.
+
 ## Share one worker across clients
 
 This optional source-installation workflow shares a running worker, in addition to the shared model configuration available to all CLI installations. Set an `OCE_API_KEY` of at least 24 characters in the environment, then run from the checkout:
@@ -168,10 +172,10 @@ Run `open-context-engine doctor` to check model configuration, Python dependenci
 
 If upgrading from the old package named `opencontextengine`, first run `npm uninstall -g opencontextengine` to avoid a command-name conflict. This leaves your saved model settings and indexes intact.
 
-For an internal upgrade, install the new archive and rerun setup:
+To upgrade from npm and reuse your saved settings:
 
 ```sh
-npm install -g /path/to/new-open-context-engine.tgz
+npm install -g open-context-engine@latest
 open-context-engine setup
 ```
 
@@ -179,13 +183,13 @@ Press Enter to retain saved settings. Setup reuses a healthy managed Python runt
 
 First-time setup requires network access to npm/PyPI and tokenizer data. If Python is missing or lacks `venv`/`pip`, install Python 3.10+ with those components, then rerun setup. The CLI does not install system Node, Python, Git, or Go.
 
-## Internal testing checklist
+## Installation verification
 
-1. Install the supplied tarball on macOS or Linux and run setup with your model endpoints.
+1. Install from npm (or an internal tarball) on macOS or Linux and run setup with your model endpoints.
 2. Paste the generated MCP configuration into your client, restart it, and search a small project.
 3. Save an edit, add a file, and delete a file; verify search returns current source.
 4. Switch to another project and back; verify the results belong to the requested project.
-5. Restart the client and reinstall the archive; verify model settings and compatible indexes are retained.
+5. Restart the client and reinstall the package; verify model settings and compatible indexes are retained.
 
 For issues, include the CLI version, operating system, client name, and the error message. Keep API keys and private source code out of reports.
 

package/docs/RERANKER_API.md

@@ -6,6 +6,8 @@ The published benchmarks used Qwen3-Reranker-4B with an optional batch API. Its
 
 ## API modes
 
+The paths below belong to this reference server. For another provider, OpenContextEngine appends `/rerank` to `RERANK_BASE_URL`; a `/v1` prefix is only needed if that provider requires it.
+
 | Mode | Endpoint | Request | Response |
 | --- | --- | --- | --- |
 | Default | `POST /v1/rerank` | `model`, `query`, `documents`, `top_n` | `results` with original document `index` and `relevance_score` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-context-engine",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "engines": {
     "node": ">=22.14"
@@ -36,6 +36,7 @@
     "linux"
   ],
   "files": [
+    "README.zh-CN.md",
     "bin/",
     "src/config.mjs",
     "src/environment.mjs",

package/src/mcp.mjs

@@ -15,7 +15,7 @@ export function createMcpServer(config, {resolveConfig, automatic = false} = {})
   }
   const pathSchema = z.string().min(1).describe('Absolute path to the project directory. Required in automatic workspace mode.');
   const directoryPath = automatic ? pathSchema : pathSchema.optional();
-  const server = new McpServer({name:'open-context-engine',version:'0.1.0'}, {
+  const server = new McpServer({name:'open-context-engine',version:'0.1.1'}, {
     instructions:workspaceInstructions + 'Search for source evidence. Results include source paths and line numbers. '
       + 'Search waits for saved file changes to be indexed. If an update is pending or fails, inspect index_status and retry after it completes. '
       + 'Read target files again before editing, because code may change after a search.',