scythe-context-mcp 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,197 @@
+# Scythe Context MCP
+
+[![CI](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+[![Node.js >=24.11](https://img.shields.io/badge/Node.js-%3E%3D24.11-339933.svg)](package.json)
+
+[繁體中文](README.md) | [English](README.en.md) | [简体中文](README.zh-CN.md)
+
+Scythe Context MCP 是给 Codex App / Codex CLI 使用的本地代码上下文引擎。它在 repo 内建立 SQLite/sqlite-vec 索引，结合语义搜索、关键字搜索、符号/依赖关系与 context packing，让 Codex 更快拿到可操作的文件、行号、片段与相关路径。
+
+## 为什么用它
+
+- **本地优先**：metadata、FTS 与向量索引都存在 repo 内的 `.scythe-context/`。
+- **混合搜索**：结合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠单一召回方式。
+- **Codex 友好输出**：返回 line ranges、snippets、match reasons、grep keywords、related files 与 suggested paths。
+- **可接自己的 provider**：支持官方 Gemini API，也支持第三方 Gemini-compatible v1beta proxy。
+- **可诊断**：内置 provider probe、index freshness、embedding coverage 与可修复建议。
+
+隐私提醒：只有在执行 embedding 相关功能时，query 或 chunk text 才会发送到你配置的 Gemini-compatible endpoint。第三方 proxy 应视为可以看到这些文字。
+
+## 功能状态
+
+已完成：
+
+- repo 扫描、binary/large-file skip、chunking
+- SQLite metadata、SQLite FTS5、sqlite-vec 向量索引
+- Gemini Embedding 2 provider 与 batch fallback
+- semantic / keyword / hybrid search
+- 轻量 symbol/dependency graph
+- related-file lookup、bounded multi-hop traversal
+- `repo_context_pack` context budgeting 与 related snippet packing
+- provider diagnostics 与 index freshness diagnostics
+
+下一步：
+
+- provider capability cache
+- 更完整的安装/原生依赖 doctor
+- embedding 失败时的 keyword-only fallback
+- 必要时加入 tree-sitter symbol extraction
+
+## 安装
+
+### 从 npm 安装
+
+使用 npm 安装全局命令：
+
+```bash
+npm install -g scythe-context-mcp
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
+cd scythe-context-mcp
+npm install
+cp .env.example .env
+npm run build
+```
+
+Runtime 目标是 Node.js 24 LTS。Node 26 可能可用，但在进入 LTS 前不作为主要验收基准。
+
+旧项目名 `repo-beacon-mcp` 已改为 `scythe-context-mcp`。旧的 `REPO_BEACON_*` 环境变量仍作为 fallback 兼容，但新配置应改用 `SCYTHE_CONTEXT_*`。
+
+## Codex 配置
+
+### npm binary
+
+如果已用 npm 全局安装：
+
+```toml
+[mcp_servers.scythe_context]
+command = "scythe-context-mcp"
+enabled = true
+required = false
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+env_vars = ["GEMINI_API_KEY"]
+enabled_tools = [
+  "repo_index_status",
+  "repo_reindex",
+  "repo_context_pack",
+  "repo_semantic_search",
+  "repo_related_files",
+  "gemini_embedding_probe"
+]
+
+[mcp_servers.scythe_context.env]
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+### 本地 checkout
+
+如果从源码执行：
+
+```toml
+[mcp_servers.scythe_context]
+command = "node"
+args = ["/path/to/scythe-context-mcp/dist/index.js"]
+cwd = "/path/to/scythe-context-mcp"
+enabled = true
+required = false
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+env_vars = ["GEMINI_API_KEY"]
+
+[mcp_servers.scythe_context.env]
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+### 第三方 v1beta proxy
+
+```toml
+[mcp_servers.scythe_context.env]
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_AUTH_MODE = "bearer"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
+
+支持的 auth mode：
+
+- `x-goog-api-key`
+- `bearer`
+- `query`
+
+启动 Codex 前在 shell 或系统环境中设置 `GEMINI_API_KEY`，避免把 key 写进会同步或会提交的配置文件。
+
+## 常用工作流
+
+1. 先检查索引状态：
+
+   ```text
+   repo_index_status
+   ```
+
+2. 如果 metadata 不存在或 freshness 显示 stale：
+
+   ```text
+   repo_reindex({ "dry_run": false })
+   ```
+
+3. 需要语义搜索或 context pack 时，再建立 embeddings：
+
+   ```text
+   repo_reindex({ "dry_run": false, "index_embeddings": true })
+   ```
+
+4. 让 Codex 针对任务拿上下文：
+
+   ```text
+   repo_context_pack({ "query": "where is auth token validation handled?" })
+   ```
+
+5. 对某个命中文件展开 imports / reverse imports：
+
+   ```text
+   repo_related_files({ "path": "src/server/auth.ts" })
+   ```
+
+## MCP 工具
+
+| Tool | 用途 |
+| --- | --- |
+| `repo_index_status` | 查看 index path、metadata/embedding coverage、freshness diagnostics 与建议动作。 |
+| `repo_reindex` | 扫描项目并写入 metadata；设置 `index_embeddings=true` 时才会调用 embedding provider。 |
+| `repo_context_pack` | 针对任务查询打包 primary snippets、match reasons、related files 与 suggested paths。 |
+| `repo_semantic_search` | 对已索引 chunks 做 hybrid 或 semantic search，适合排查 ranking。 |
+| `repo_related_files` | 查看单一文件的 symbols、imports、importedBy。 |
+| `gemini_embedding_probe` | 测试 Gemini 或 proxy 兼容性，返回 endpoint、latency、错误分类与可修复建议。 |
+
+## 隐私与本地文件
+
+- `.scythe-context/`: 默认索引目录，不提交。
+- `.repo-beacon/`: 旧索引目录名称，仍被 ignore。
+- `local/`: 私密 API 测试文件、参考 HTML、截图等本地资料，不提交。
+- `.env`: 本地配置，不提交。
+
+不要把 API key、proxy token、私有代码片段或 index database 放进 issue、PR 或公开 logs。
+
+## 文档
+
+- [架构设计](docs/architecture.md)
+- [开发计划](docs/development-plan.md)
+- [Gemini 兼容性](docs/gemini-compatibility.md)
+- [技术栈](docs/tech-stack.md)
+- [Codex 集成审查](docs/codex-integration.md)
+
+## 开发与发布检查
+
+```bash
+npm test
+npm run build
+npm audit --omit=dev
+npm pack --dry-run
+```
+
+确认 package 不包含 `.env`、`.scythe-context/`, `.repo-beacon/`, `local/`, API key 或私密参考文件。

package/dist/config.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import process from "node:process";
+import { DEFAULT_INDEXING_LIMITS } from "./indexing/defaults.js";
+function numberFromEnv(name, fallback) {
+    const value = process.env[name];
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive number`);
+    }
+    return parsed;
+}
+function envValue(name, legacyName) {
+    return process.env[name] || (legacyName ? process.env[legacyName] : undefined);
+}
+function numberFromEnvAlias(name, legacyName, fallback) {
+    const value = envValue(name, legacyName);
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} or ${legacyName} must be a positive number`);
+    }
+    return parsed;
+}
+function authModeFromEnv(value) {
+    if (!value)
+        return "x-goog-api-key";
+    if (value === "x-goog-api-key" || value === "bearer" || value === "query") {
+        return value;
+    }
+    throw new Error("GEMINI_AUTH_MODE must be one of: x-goog-api-key, bearer, query");
+}
+export function loadConfig() {
+    return {
+        defaultProjectPath: path.resolve(envValue("SCYTHE_CONTEXT_DEFAULT_PROJECT", "REPO_BEACON_DEFAULT_PROJECT") || process.cwd()),
+        indexDirName: envValue("SCYTHE_CONTEXT_INDEX_DIR", "REPO_BEACON_INDEX_DIR") || ".scythe-context",
+        indexing: {
+            maxFileBytes: numberFromEnvAlias("SCYTHE_CONTEXT_MAX_FILE_BYTES", "REPO_BEACON_MAX_FILE_BYTES", DEFAULT_INDEXING_LIMITS.maxFileBytes) ??
+                DEFAULT_INDEXING_LIMITS.maxFileBytes,
+            targetChunkChars: numberFromEnvAlias("SCYTHE_CONTEXT_TARGET_CHUNK_CHARS", "REPO_BEACON_TARGET_CHUNK_CHARS", DEFAULT_INDEXING_LIMITS.targetChunkChars) ??
+                DEFAULT_INDEXING_LIMITS.targetChunkChars,
+            chunkOverlapChars: numberFromEnvAlias("SCYTHE_CONTEXT_CHUNK_OVERLAP_CHARS", "REPO_BEACON_CHUNK_OVERLAP_CHARS", DEFAULT_INDEXING_LIMITS.chunkOverlapChars) ??
+                DEFAULT_INDEXING_LIMITS.chunkOverlapChars,
+            maxChunksPerFile: numberFromEnvAlias("SCYTHE_CONTEXT_MAX_CHUNKS_PER_FILE", "REPO_BEACON_MAX_CHUNKS_PER_FILE", DEFAULT_INDEXING_LIMITS.maxChunksPerFile) ??
+                DEFAULT_INDEXING_LIMITS.maxChunksPerFile,
+            embeddingBatchSize: numberFromEnvAlias("SCYTHE_CONTEXT_EMBEDDING_BATCH_SIZE", "REPO_BEACON_EMBEDDING_BATCH_SIZE", 16) ?? 16,
+            maxEmbeddingChunks: numberFromEnvAlias("SCYTHE_CONTEXT_MAX_EMBEDDING_CHUNKS", "REPO_BEACON_MAX_EMBEDDING_CHUNKS", 256) ?? 256,
+        },
+        gemini: {
+            apiKey: process.env.GEMINI_API_KEY,
+            baseUrl: process.env.GEMINI_BASE_URL || "https://generativelanguage.googleapis.com/v1beta",
+            model: process.env.GEMINI_MODEL || "gemini-embedding-2",
+            outputDimensionality: numberFromEnv("GEMINI_OUTPUT_DIMENSIONALITY", 1536),
+            authMode: authModeFromEnv(process.env.GEMINI_AUTH_MODE),
+            apiKeyHeader: process.env.GEMINI_API_KEY_HEADER || "x-goog-api-key",
+            apiKeyQueryParam: process.env.GEMINI_API_KEY_QUERY_PARAM || "key",
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { registerTools } from "./tools/registerTools.js";
+const config = loadConfig();
+const server = new McpServer({
+    name: "scythe-context-mcp",
+    version: "0.1.0",
+}, {
+    instructions: "Scythe Context is a local code-context MCP server for Codex. Use repo_index_status first, repo_reindex(dry_run=false) when metadata is missing or stale, and repo_context_pack for task lookup. Only set index_embeddings=true when semantic vectors are needed because chunk text is sent to the configured embedding endpoint. Keep max_context_chars and max_related_context_chars bounded. Use repo_semantic_search for ranking/debugging and repo_related_files for a focused file graph.",
+});
+registerTools(server, config);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/indexing/binary.js

@@ -0,0 +1,15 @@
+import { TextDecoder } from "node:util";
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+export function isProbablyBinary(buffer) {
+    if (buffer.length === 0)
+        return false;
+    if (buffer.includes(0))
+        return true;
+    try {
+        utf8Decoder.decode(buffer);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/indexing/chunker.js

@@ -0,0 +1,64 @@
+import { sha256Hex } from "./hash.js";
+const MAX_LINE_EXTENSION_CHARS = 240;
+function lineEndIndex(text, startIndex) {
+    const nextNewline = text.indexOf("\n", startIndex);
+    return nextNewline === -1 ? text.length : nextNewline + 1;
+}
+function chooseChunkEnd(text, targetEnd) {
+    if (targetEnd >= text.length)
+        return text.length;
+    const nextNewline = text.indexOf("\n", targetEnd);
+    if (nextNewline !== -1 && nextNewline - targetEnd <= MAX_LINE_EXTENSION_CHARS) {
+        return nextNewline + 1;
+    }
+    return targetEnd;
+}
+function countNewlines(text) {
+    return text.length === 0 ? 0 : (text.match(/\n/g) || []).length;
+}
+function findOverlapStart(text, chunkStart, chunkEnd, overlapChars) {
+    if (overlapChars <= 0)
+        return chunkEnd;
+    const approximateStart = Math.max(chunkStart, chunkEnd - overlapChars);
+    const nextLineStart = lineEndIndex(text, approximateStart);
+    return nextLineStart > chunkEnd ? approximateStart : nextLineStart;
+}
+export function chunkText(relativePath, text, limits) {
+    if (text.length === 0) {
+        return [
+            {
+                relativePath,
+                startLine: 1,
+                endLine: 1,
+                text: "",
+                hash: sha256Hex(`${relativePath}\n1\n1\n`),
+            },
+        ];
+    }
+    const chunks = [];
+    let start = 0;
+    let startLine = 1;
+    while (start < text.length && chunks.length < limits.maxChunksPerFile) {
+        const targetEnd = Math.min(text.length, start + limits.targetChunkChars);
+        let end = chooseChunkEnd(text, targetEnd);
+        if (end <= start)
+            end = Math.min(text.length, start + limits.targetChunkChars);
+        const chunkTextValue = text.slice(start, end);
+        const lineSpan = Math.max(1, countNewlines(chunkTextValue) + (chunkTextValue.endsWith("\n") ? 0 : 1));
+        const endLine = startLine + lineSpan - 1;
+        chunks.push({
+            relativePath,
+            startLine,
+            endLine,
+            text: chunkTextValue,
+            hash: sha256Hex(`${relativePath}\n${startLine}\n${endLine}\n${chunkTextValue}`),
+        });
+        if (end >= text.length)
+            break;
+        const nextStart = findOverlapStart(text, start, end, limits.chunkOverlapChars);
+        const advancedStart = nextStart <= start ? end : nextStart;
+        startLine += countNewlines(text.slice(start, advancedStart));
+        start = advancedStart;
+    }
+    return chunks;
+}

package/dist/indexing/contextPack.js

@@ -0,0 +1,54 @@
+import { classifyRelatedPath } from "./relatedFiles.js";
+import { formatSearchResults, } from "./resultFormat.js";
+function addUnique(values, value) {
+    if (value && !values.includes(value))
+        values.push(value);
+}
+function compactRelatedFile(related, maxRelatedItems) {
+    return {
+        sourcePath: related.path,
+        role: classifyRelatedPath(related.path),
+        ...("depth" in related ? { depth: related.depth, via: related.via } : {}),
+        symbols: related.symbols.slice(0, maxRelatedItems),
+        imports: related.imports.slice(0, maxRelatedItems),
+        importedBy: related.importedBy.slice(0, maxRelatedItems),
+    };
+}
+export function buildContextPack(query, searchResults, relatedFiles, options) {
+    const formatted = formatSearchResults(query, searchResults, { maxContextChars: options.maxContextChars });
+    const relatedSnippetPack = options.relatedSnippets ??
+        {
+            snippets: [],
+            summary: {
+                maxRelatedContextChars: 0,
+                usedRelatedContextChars: 0,
+                relatedSnippetCount: 0,
+                truncatedRelatedSnippets: 0,
+            },
+        };
+    const primaryPaths = formatted.results.map((result) => result.path);
+    const related = relatedFiles
+        .slice(0, options.maxRelatedFiles)
+        .map((item) => compactRelatedFile(item, options.maxRelatedItems));
+    const suggestedPaths = [];
+    for (const path of primaryPaths)
+        addUnique(suggestedPaths, path);
+    for (const item of related) {
+        for (const dependency of item.imports)
+            addUnique(suggestedPaths, dependency.resolvedPath);
+        for (const reverseDependency of item.importedBy)
+            addUnique(suggestedPaths, reverseDependency.path);
+    }
+    return {
+        primaryResults: formatted.results,
+        relatedFiles: related,
+        relatedSnippets: relatedSnippetPack.snippets,
+        suggestedPaths,
+        context: {
+            ...formatted.summary,
+            ...relatedSnippetPack.summary,
+            primaryResultCount: formatted.results.length,
+            relatedFileCount: related.length,
+        },
+    };
+}

package/dist/indexing/defaults.js

@@ -0,0 +1,6 @@
+export const DEFAULT_INDEXING_LIMITS = {
+    maxFileBytes: 512 * 1024,
+    targetChunkChars: 4_000,
+    chunkOverlapChars: 400,
+    maxChunksPerFile: 80,
+};

package/dist/indexing/dryRun.js

@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { chunkText } from "./chunker.js";
+import { DEFAULT_INDEXING_LIMITS } from "./defaults.js";
+import { sha256Hex } from "./hash.js";
+import { scanProject } from "./scanner.js";
+export function resolveIndexingLimits(options) {
+    return {
+        maxFileBytes: options.maxFileBytes ?? DEFAULT_INDEXING_LIMITS.maxFileBytes,
+        targetChunkChars: options.targetChunkChars ?? DEFAULT_INDEXING_LIMITS.targetChunkChars,
+        chunkOverlapChars: options.chunkOverlapChars ?? DEFAULT_INDEXING_LIMITS.chunkOverlapChars,
+        maxChunksPerFile: options.maxChunksPerFile ?? DEFAULT_INDEXING_LIMITS.maxChunksPerFile,
+    };
+}
+export async function reindexDryRun(options) {
+    const projectPath = path.resolve(options.projectPath);
+    const limits = resolveIndexingLimits(options);
+    const scan = await scanProject(projectPath, limits);
+    const files = [];
+    let chunkCount = 0;
+    let byteCount = 0;
+    for (const file of scan.files) {
+        const content = await fs.readFile(file.absolutePath, "utf8");
+        const chunks = chunkText(file.relativePath, content, limits);
+        chunkCount += chunks.length;
+        byteCount += file.size;
+        files.push({
+            path: file.relativePath,
+            size: file.size,
+            hash: sha256Hex(content),
+            chunks: chunks.length,
+        });
+    }
+    return {
+        projectPath,
+        dryRun: true,
+        limits,
+        stats: {
+            scannedFiles: scan.files.length + scan.skipped.length,
+            indexedFiles: scan.files.length,
+            skippedFiles: scan.skipped.length,
+            chunks: chunkCount,
+            bytes: byteCount,
+        },
+        files,
+        skipped: scan.skipped,
+    };
+}

package/dist/indexing/embeddingWriter.js

@@ -0,0 +1,102 @@
+import Database from "better-sqlite3";
+import { sha256Hex } from "./hash.js";
+import { getOrCreateEmbeddingRecord, getOrCreateEmbeddingSet, initializeStorageSchema, vectorTableName, } from "../storage/schema.js";
+import { vectorToFloat32Buffer } from "../storage/sqliteVec.js";
+function chunkTitle(chunk) {
+    return chunk.title || `${chunk.path}:${chunk.startLine}-${chunk.endLine}`;
+}
+function toEmbeddingRequest(chunk) {
+    return {
+        kind: "document",
+        title: chunkTitle(chunk),
+        text: chunk.text,
+    };
+}
+function chunkArray(items, batchSize) {
+    const batches = [];
+    for (let index = 0; index < items.length; index += batchSize) {
+        batches.push(items.slice(index, index + batchSize));
+    }
+    return batches;
+}
+async function embedWithFallback(provider, requests) {
+    try {
+        return { results: await provider.embedBatch(requests), usedFallback: false };
+    }
+    catch (error) {
+        const results = [];
+        for (const request of requests) {
+            results.push(await provider.embed(request));
+        }
+        return { results, usedFallback: true };
+    }
+}
+export async function indexMissingEmbeddings(options) {
+    if (!Number.isInteger(options.batchSize) || options.batchSize <= 0) {
+        throw new Error("batchSize must be a positive integer");
+    }
+    const db = new Database(options.dbPath);
+    let embeddedChunks = 0;
+    let batchFallbacks = 0;
+    let batches = 0;
+    try {
+        initializeStorageSchema(db, { vectorDimensions: options.dimensions });
+        const embeddingSetId = getOrCreateEmbeddingSet(db, {
+            provider: options.providerName,
+            baseUrlHash: sha256Hex(options.providerBaseUrl),
+            model: options.model,
+            dimensions: options.dimensions,
+        });
+        const limitSql = options.maxChunks ? "limit @maxChunks" : "";
+        const pendingChunks = db
+            .prepare(`
+        select chunks.id, files.path, chunks.start_line as startLine, chunks.end_line as endLine,
+               chunks.title, chunks.text
+        from chunks
+        join files on files.id = chunks.file_id
+        left join embeddings
+          on embeddings.chunk_id = chunks.id
+         and embeddings.embedding_set_id = @embeddingSetId
+        where embeddings.id is null
+        order by files.path, chunks.start_line
+        ${limitSql}
+      `)
+            .all({ embeddingSetId, maxChunks: options.maxChunks });
+        const insertVector = db.prepare(`insert or replace into ${vectorTableName(options.dimensions)}(rowid, embedding) values (?, ?)`);
+        const writeEmbedding = db.transaction((chunkId, vector) => {
+            const embeddingId = getOrCreateEmbeddingRecord(db, { chunkId, embeddingSetId });
+            insertVector.run(BigInt(embeddingId), vectorToFloat32Buffer(vector, options.dimensions));
+        });
+        for (const batch of chunkArray(pendingChunks, options.batchSize)) {
+            batches += 1;
+            const { results, usedFallback } = await embedWithFallback(options.provider, batch.map((chunk) => toEmbeddingRequest(chunk)));
+            if (usedFallback)
+                batchFallbacks += 1;
+            for (let index = 0; index < batch.length; index += 1) {
+                const chunk = batch[index];
+                const result = results[index];
+                if (result.dimensions !== options.dimensions) {
+                    throw new Error(`Embedding dimensions mismatch for chunk ${chunk.id}: expected ${options.dimensions}, got ${result.dimensions}`);
+                }
+                writeEmbedding(chunk.id, result.vector);
+                embeddedChunks += 1;
+            }
+        }
+        return {
+            status: "embeddings_indexed",
+            dbPath: options.dbPath,
+            embeddingSetId,
+            dimensions: options.dimensions,
+            stats: {
+                pendingChunks: pendingChunks.length,
+                embeddedChunks,
+                skippedChunks: 0,
+                batches,
+                batchFallbacks,
+            },
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/indexing/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}

package/dist/indexing/hybridSearch.js

@@ -0,0 +1,67 @@
+import { searchByKeyword } from "./keywordSearch.js";
+import { searchByVector } from "./semanticSearch.js";
+function keyOf(result) {
+    return `${result.path}:${result.startLine}:${result.endLine}`;
+}
+function semanticScore(result, index) {
+    return 1 / (1 + Math.max(0, result.distance)) + Math.max(0, 0.2 - index * 0.01);
+}
+function keywordScore(result, index) {
+    return 1.2 + Math.max(0, 0.3 - index * 0.02) + Math.min(0.5, Math.abs(result.score) / 10);
+}
+export function mergeHybridResults(semanticResults, keywordResults, maxResults) {
+    const merged = new Map();
+    semanticResults.forEach((result, index) => {
+        merged.set(keyOf(result), {
+            path: result.path,
+            startLine: result.startLine,
+            endLine: result.endLine,
+            score: semanticScore(result, index),
+            distance: result.distance,
+            snippet: result.snippet,
+            matchTypes: ["semantic"],
+        });
+    });
+    keywordResults.forEach((result, index) => {
+        const key = keyOf(result);
+        const score = keywordScore(result, index);
+        const existing = merged.get(key);
+        if (existing) {
+            existing.score += score;
+            existing.keywordScore = result.score;
+            if (!existing.matchTypes.includes("keyword"))
+                existing.matchTypes.push("keyword");
+            if (result.snippet.length > existing.snippet.length)
+                existing.snippet = result.snippet;
+            return;
+        }
+        merged.set(key, {
+            path: result.path,
+            startLine: result.startLine,
+            endLine: result.endLine,
+            score,
+            keywordScore: result.score,
+            snippet: result.snippet,
+            matchTypes: ["keyword"],
+        });
+    });
+    return Array.from(merged.values())
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.startLine - b.startLine)
+        .slice(0, maxResults);
+}
+export function searchHybrid(options) {
+    const semanticResults = searchByVector({
+        dbPath: options.dbPath,
+        dimensions: options.dimensions,
+        queryVector: options.queryVector,
+        maxResults: Math.max(options.maxResults * 2, options.maxResults),
+        maxSnippetChars: options.maxSnippetChars,
+    });
+    const keywordResults = searchByKeyword({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: Math.max(options.maxResults * 2, options.maxResults),
+        maxSnippetChars: options.maxSnippetChars,
+    });
+    return mergeHybridResults(semanticResults, keywordResults, options.maxResults);
+}