@minko-ai/minko 0.1.0 → 0.1.1

package/dist/rag/index.js

@@ -0,0 +1,373 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', '.minko', 'dist', 'build', 'out', '.next', '.nuxt',
+    'coverage', 'target', 'vendor', '__pycache__', '.venv', 'venv', '.idea',
+    '.vscode', '.cache', '.turbo',
+]);
+const IGNORED_FILES = new Set([
+    'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'Cargo.lock', 'go.sum',
+    'composer.lock', 'poetry.lock',
+]);
+const IGNORED_EXT = /\.(png|jpe?g|gif|webp|ico|bmp|tiff?|pdf|zip|gz|tgz|rar|7z|xz|bz2|exe|dll|so|dylib|bin|o|a|class|jar|war|mp3|mp4|mov|avi|mkv|wav|flac|woff2?|ttf|otf|eot|sqlite|db)$/i;
+/** Never feed credentials into the model context. */
+const SENSITIVE = /^(\.env(\..*)?|\.npmrc|\.netrc|id_rsa|id_ed25519|.*\.(pem|key|pfx|p12))$/i;
+/**
+ * A lightweight local retrieval index: line-based chunks scored with BM25.
+ * It is intentionally dependency-free and works offline.
+ */
+export class WorkspaceIndex {
+    root;
+    options;
+    chunks = [];
+    semanticError = null;
+    df = new Map();
+    avgLength = 0;
+    builtAt = 0;
+    building = null;
+    queryVectors = new Map();
+    constructor(root, options = {}) {
+        this.root = path.resolve(root);
+        this.options = {
+            maxFiles: 3_000,
+            maxFileBytes: 256 * 1024,
+            chunkLines: 40,
+            chunkOverlap: 8,
+            maxChunks: 12_000,
+            maxChunkChars: 4_000,
+            maxEmbeddingChunks: 1_000,
+            ...options,
+        };
+    }
+    get semanticActive() {
+        return Boolean(this.options.embedder) && this.chunks.some((chunk) => chunk.embedding);
+    }
+    stats() {
+        return {
+            chunks: this.chunks.length,
+            files: new Set(this.chunks.map((chunk) => chunk.path)).size,
+            semantic: this.semanticActive,
+            semanticError: this.semanticError,
+        };
+    }
+    /** Rebuilds when the index is older than maxAgeMs. 0 forces a rebuild. */
+    async ensureFresh(maxAgeMs) {
+        if (this.builtAt > 0 && maxAgeMs > 0 && Date.now() - this.builtAt <= maxAgeMs) {
+            return;
+        }
+        await this.rebuild();
+    }
+    async rebuild() {
+        if (this.building) {
+            await this.building;
+            return;
+        }
+        this.building = this.doRebuild().finally(() => {
+            this.building = null;
+        });
+        await this.building;
+    }
+    search(query, topK = 6) {
+        const terms = [...new Set(tokenize(query))];
+        if (terms.length === 0 || this.chunks.length === 0) {
+            return [];
+        }
+        const phrase = query.trim().toLowerCase();
+        const hits = [];
+        for (const chunk of this.chunks) {
+            let score = this.scoreChunk(chunk, terms);
+            if (phrase.length >= 2 && chunk.text.toLowerCase().includes(phrase)) {
+                score += 3;
+            }
+            if (score > 0) {
+                hits.push(toHit(chunk, score));
+            }
+        }
+        return rank(hits, topK);
+    }
+    /** BM25 + embeddings when configured; falls back to BM25 on any failure. */
+    async searchAsync(query, topK = 6) {
+        const embedder = this.options.embedder;
+        if (!embedder || !this.semanticActive) {
+            return this.search(query, topK);
+        }
+        const terms = [...new Set(tokenize(query))];
+        let queryVector = this.queryVectors.get(query);
+        if (!queryVector) {
+            try {
+                const [vector] = await embedder.embed([query]);
+                if (!vector) {
+                    throw new Error('embedding 返回为空');
+                }
+                if (this.queryVectors.size >= 200) {
+                    this.queryVectors.clear();
+                }
+                this.queryVectors.set(query, vector);
+                queryVector = vector;
+            }
+            catch (error) {
+                this.semanticError = error instanceof Error ? error.message : String(error);
+                return this.search(query, topK);
+            }
+        }
+        let maxBm25 = 1;
+        const scored = this.chunks.map((chunk) => {
+            const bm25 = this.scoreChunk(chunk, terms);
+            if (bm25 > maxBm25) {
+                maxBm25 = bm25;
+            }
+            return { chunk, bm25 };
+        });
+        const hits = [];
+        for (const { chunk, bm25 } of scored) {
+            const semantic = chunk.embedding ? cosine(queryVector, chunk.embedding) : 0;
+            const score = 0.45 * (bm25 / maxBm25) + 0.55 * Math.max(0, semantic);
+            if (score > 0.02) {
+                hits.push({ ...toHit(chunk, score), semantic });
+            }
+        }
+        return rank(hits, topK);
+    }
+    scoreChunk(chunk, terms) {
+        const total = this.chunks.length;
+        const k1 = 1.2;
+        const b = 0.75;
+        let score = 0;
+        for (const term of terms) {
+            const tf = chunk.tokens.get(term) ?? 0;
+            if (tf === 0) {
+                continue;
+            }
+            const df = this.df.get(term) ?? 0;
+            const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));
+            const denominator = tf + k1 * (1 - b + b * (chunk.length / (this.avgLength || 1)));
+            score += idf * (tf * (k1 + 1)) / denominator;
+        }
+        return score;
+    }
+    async doRebuild() {
+        const files = await walkFiles(this.root, this.options);
+        const chunks = [];
+        const step = Math.max(1, this.options.chunkLines - this.options.chunkOverlap);
+        for (const file of files) {
+            if (chunks.length >= this.options.maxChunks) {
+                break;
+            }
+            let text;
+            try {
+                const stat = await fs.promises.stat(file);
+                if (stat.size > this.options.maxFileBytes) {
+                    continue;
+                }
+                text = await fs.promises.readFile(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (text.includes('\u0000') || text.trim().length === 0) {
+                continue;
+            }
+            const relative = displayPath(this.root, file);
+            const lines = text.split(/\r?\n/);
+            for (let start = 0; start < lines.length; start += step) {
+                if (chunks.length >= this.options.maxChunks) {
+                    break;
+                }
+                const end = Math.min(lines.length, start + this.options.chunkLines);
+                const block = lines.slice(start, end).join('\n');
+                if (block.trim().length === 0) {
+                    if (end >= lines.length) {
+                        break;
+                    }
+                    continue;
+                }
+                for (const piece of splitOversized(block, this.options.maxChunkChars)) {
+                    if (chunks.length >= this.options.maxChunks) {
+                        break;
+                    }
+                    chunks.push(makeChunk(relative, start + 1, end, piece));
+                }
+                if (end >= lines.length) {
+                    break;
+                }
+            }
+        }
+        this.semanticError = null;
+        this.queryVectors.clear();
+        if (this.options.embedder) {
+            try {
+                await this.attachEmbeddings(chunks);
+            }
+            catch (error) {
+                this.semanticError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const df = new Map();
+        let totalLength = 0;
+        for (const chunk of chunks) {
+            totalLength += chunk.length;
+            for (const term of chunk.tokens.keys()) {
+                df.set(term, (df.get(term) ?? 0) + 1);
+            }
+        }
+        this.chunks = chunks;
+        this.df = df;
+        this.avgLength = chunks.length > 0 ? totalLength / chunks.length : 0;
+        this.builtAt = Date.now();
+    }
+    async attachEmbeddings(chunks) {
+        const embedder = this.options.embedder;
+        if (!embedder) {
+            return;
+        }
+        const target = chunks.slice(0, this.options.maxEmbeddingChunks);
+        const missing = [];
+        for (const chunk of target) {
+            const hash = crypto.createHash('sha1')
+                .update(embedder.model + '\n' + chunk.text)
+                .digest('hex');
+            const cached = this.options.embeddingCache?.get(hash);
+            if (cached) {
+                chunk.embedding = cached;
+            }
+            else {
+                missing.push({ chunk, hash });
+            }
+        }
+        if (missing.length === 0) {
+            return;
+        }
+        const vectors = await embedder.embed(missing.map((entry) => entry.chunk.text));
+        if (vectors.length !== missing.length) {
+            throw new Error('embedding 返回数量不匹配：期望 ' + missing.length + '，实际 ' + vectors.length);
+        }
+        for (let index = 0; index < missing.length; index += 1) {
+            missing[index].chunk.embedding = vectors[index];
+            this.options.embeddingCache?.set(missing[index].hash, vectors[index]);
+        }
+        this.options.embeddingCache?.save();
+    }
+}
+function toHit(chunk, score) {
+    return {
+        path: chunk.path,
+        startLine: chunk.startLine,
+        endLine: chunk.endLine,
+        text: chunk.text,
+        score,
+    };
+}
+function rank(hits, topK) {
+    hits.sort((a, b) => b.score - a.score
+        || a.path.localeCompare(b.path)
+        || a.startLine - b.startLine);
+    return hits.slice(0, Math.max(1, Math.min(topK, 20)));
+}
+function cosine(a, b) {
+    const length = Math.min(a.length, b.length);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let index = 0; index < length; index += 1) {
+        dot += a[index] * b[index];
+        normA += a[index] * a[index];
+        normB += b[index] * b[index];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dot / Math.sqrt(normA * normB);
+}
+/** Latin words plus CJK bigrams, which work without a dictionary. */
+export function tokenize(text) {
+    const lower = text.toLowerCase();
+    const tokens = lower.match(/[a-z0-9_]{2,}/g) ?? [];
+    const cjk = lower.match(/[㐀-鿿]+/g) ?? [];
+    for (const sequence of cjk) {
+        if (sequence.length === 1) {
+            tokens.push(sequence);
+            continue;
+        }
+        for (let index = 0; index < sequence.length - 1; index += 1) {
+            tokens.push(sequence.slice(index, index + 2));
+        }
+    }
+    return tokens;
+}
+function makeChunk(filePath, startLine, endLine, text) {
+    const tokens = new Map();
+    let length = 0;
+    for (const term of tokenize(text)) {
+        tokens.set(term, (tokens.get(term) ?? 0) + 1);
+        length += 1;
+    }
+    // File names are strong signals ("auth.ts" for an auth question).
+    for (const term of tokenize(filePath)) {
+        tokens.set(term, (tokens.get(term) ?? 0) + 1);
+        length += 1;
+    }
+    return { path: filePath, startLine, endLine, text, tokens, length };
+}
+function splitOversized(text, max) {
+    if (text.length <= max) {
+        return [text];
+    }
+    const pieces = [];
+    const overlap = Math.min(200, Math.floor(max / 10));
+    const step = Math.max(1, max - overlap);
+    for (let index = 0; index < text.length; index += step) {
+        pieces.push(text.slice(index, index + max));
+        if (index + max >= text.length) {
+            break;
+        }
+    }
+    return pieces;
+}
+async function walkFiles(root, options) {
+    const files = [];
+    const stack = [root];
+    while (stack.length > 0 && files.length < options.maxFiles) {
+        const dir = stack.pop();
+        if (!dir) {
+            break;
+        }
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (files.length >= options.maxFiles) {
+                break;
+            }
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name)) {
+                    continue;
+                }
+                stack.push(path.join(dir, entry.name));
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            if (IGNORED_DIRS.has(entry.name) || IGNORED_FILES.has(entry.name)) {
+                continue;
+            }
+            if (IGNORED_EXT.test(entry.name) || SENSITIVE.test(entry.name)) {
+                continue;
+            }
+            files.push(path.join(dir, entry.name));
+        }
+    }
+    return files.sort();
+}
+function displayPath(root, file) {
+    const relative = path.relative(root, file);
+    return (relative.length > 0 ? relative : file).split(path.sep).join('/');
+}

package/dist/rag/server.js

@@ -0,0 +1,167 @@
+import http from 'node:http';
+import path from 'node:path';
+import { loadConfig } from "../config/store.js";
+import { readVersion } from "../util/version.js";
+import { workspaceIndex } from "./tool.js";
+/** HTTP API compatible with the remote retrieve_context client. */
+export class RagService {
+    config;
+    root;
+    constructor(options = {}) {
+        this.config = options.config ?? loadConfig();
+        this.root = path.resolve(options.cwd ?? process.cwd());
+    }
+    async handle(method, rawUrl, body = {}) {
+        const url = new URL(rawUrl, 'http://localhost');
+        if (method === 'GET' && url.pathname === '/health') {
+            return {
+                status: 200,
+                body: { ok: true, service: 'minko-rag', version: readVersion() },
+            };
+        }
+        if (method === 'GET' && url.pathname === '/') {
+            return { status: 200, body: { ok: true }, html: INDEX_HTML };
+        }
+        if (method === 'GET' && url.pathname === '/v1/stats') {
+            const root = this.resolveRoot(url.searchParams.get('root'));
+            if (!root) {
+                return { status: 400, body: { error: 'root 不在服务工作目录内' } };
+            }
+            const index = workspaceIndex(root, this.config);
+            await index.ensureFresh(30_000);
+            return { status: 200, body: { root, ...index.stats() } };
+        }
+        if (method === 'POST' && url.pathname === '/v1/query') {
+            const query = typeof body.query === 'string' ? body.query.trim() : '';
+            if (query.length === 0) {
+                return { status: 400, body: { error: 'query is required' } };
+            }
+            const root = this.resolveRoot(typeof body.root === 'string' ? body.root : null);
+            if (!root) {
+                return { status: 400, body: { error: 'root 不在服务工作目录内' } };
+            }
+            const topK = typeof body.top_k === 'number' && Number.isFinite(body.top_k)
+                ? Math.min(20, Math.max(1, Math.floor(body.top_k)))
+                : 6;
+            const index = workspaceIndex(root, this.config);
+            await index.ensureFresh(30_000);
+            const hits = await index.searchAsync(query, topK);
+            return {
+                status: 200,
+                body: {
+                    root,
+                    results: hits.map((hit) => ({
+                        path: hit.path,
+                        start_line: hit.startLine,
+                        end_line: hit.endLine,
+                        text: hit.text,
+                        score: hit.score,
+                    })),
+                },
+            };
+        }
+        if (method === 'POST' && url.pathname === '/v1/rebuild') {
+            const root = this.resolveRoot(typeof body.root === 'string' ? body.root : null);
+            if (!root) {
+                return { status: 400, body: { error: 'root 不在服务工作目录内' } };
+            }
+            const index = workspaceIndex(root, this.config);
+            await index.ensureFresh(0);
+            return { status: 200, body: { root, ...index.stats() } };
+        }
+        return { status: 404, body: { error: 'not found' } };
+    }
+    resolveRoot(raw) {
+        if (!raw || raw.trim().length === 0) {
+            return this.root;
+        }
+        const candidate = path.resolve(this.root, raw.trim());
+        const relative = path.relative(this.root, candidate);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return null;
+        }
+        return candidate;
+    }
+}
+export async function runRagServer(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 8787;
+    const service = new RagService();
+    const server = http.createServer((request, response) => {
+        void handleRequest(service, request, response).catch((error) => {
+            writeJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    const address = server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+    process.stdout.write('RAG 服务已启动：http://' + host + ':' + actualPort + '\n');
+    process.stdout.write('  GET  /health  GET /v1/stats  POST /v1/query  POST /v1/rebuild\n');
+    const shutdown = () => {
+        server.close(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await new Promise(() => { });
+    return 0;
+}
+async function handleRequest(service, request, response) {
+    const body = await readJson(request);
+    const result = await service.handle(request.method ?? 'GET', request.url ?? '/', body);
+    if (result.html) {
+        response.writeHead(result.status, { 'content-type': 'text/html; charset=utf-8' });
+        response.end(result.html);
+        return;
+    }
+    writeJson(response, result.status, result.body);
+}
+async function readJson(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > 1024 * 1024) {
+            throw new Error('请求体过大');
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJson(response, status, body) {
+    if (response.headersSent) {
+        return;
+    }
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(body));
+}
+const INDEX_HTML = `<!doctype html>
+<html lang="zh"><head><meta charset="utf-8"><title>Minko RAG</title>
+<style>body{font-family:system-ui,sans-serif;max-width:760px;margin:40px auto;padding:0 16px}
+input,button{font-size:16px;padding:8px}pre{background:#f4f4f5;padding:16px;white-space:pre-wrap}</style>
+</head><body><h1>Minko RAG</h1>
+<p>输入查询，调用本机 <code>/v1/query</code>。</p>
+<form id="f"><input id="q" placeholder="例如：登录逻辑在哪" size="50"><button>查询</button></form>
+<pre id="out"></pre>
+<script>
+document.getElementById('f').addEventListener('submit', async (event) => {
+  event.preventDefault();
+  const query = document.getElementById('q').value;
+  const out = document.getElementById('out');
+  out.textContent = '查询中…';
+  const response = await fetch('/v1/query', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ query, top_k: 6 }) });
+  const data = await response.json();
+  out.textContent = (data.results || []).map((hit, index) => (index + 1) + '. ' + hit.path + ':' + hit.start_line + '-' + hit.end_line + '\\n' + hit.text).join('\\n\\n') || data.error || '没有结果';
+});
+</script></body></html>`;

package/dist/rag/tool.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import { WorkspaceIndex } from "./index.js";
+import { resolveEmbedding } from "./embeddings.js";
+const indexes = new Map();
+const MAX_SNIPPET = 800;
+const DEFAULT_REMOTE_TIMEOUT_MS = 10_000;
+export function workspaceIndex(cwd, config) {
+    const root = path.resolve(cwd);
+    const resolved = resolveEmbedding(config, root);
+    const key = root + '|' + (resolved?.embedder.model ?? 'bm25');
+    let index = indexes.get(key);
+    if (!index) {
+        index = new WorkspaceIndex(root, {
+            embedder: resolved?.embedder,
+            embeddingCache: resolved?.cache,
+            maxEmbeddingChunks: resolved?.maxChunks,
+        });
+        indexes.set(key, index);
+    }
+    return index;
+}
+/**
+ * Ranks workspace chunks by relevance and returns file:line snippets.
+ * Prefers a configured remote RAG service, then falls back to the local
+ * BM25/embedding index.
+ */
+export const retrieveContextTool = {
+    readOnly: true,
+    spec: {
+        name: 'retrieve_context',
+        description: '在项目里检索与问题最相关的代码和文档片段，返回 file:line 与片段。适合问“这个功能在哪实现/怎么用”。',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: '自然语言或关键词' },
+                top_k: { type: 'number', description: '返回条数，默认 6，最多 20' },
+                refresh: { type: 'boolean', description: '为 true 时强制重建索引' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    async run(args, ctx) {
+        const query = typeof args.query === 'string' ? args.query.trim() : '';
+        if (query.length === 0) {
+            throw new Error('缺少 query 参数');
+        }
+        const topK = typeof args.top_k === 'number' && Number.isFinite(args.top_k)
+            ? Math.floor(args.top_k)
+            : 6;
+        const remote = ctx.config?.rag?.remote;
+        let hits = [];
+        let note = '';
+        if (remote?.baseUrl) {
+            try {
+                hits = await remoteSearch(remote, query, topK);
+                note = '（远程 RAG）\n\n';
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                note = '（远程 RAG 不可用，已回退本地检索：' + reason + '）\n\n';
+            }
+        }
+        if (!remote?.baseUrl || note.startsWith('（远程 RAG 不可用')) {
+            const index = workspaceIndex(ctx.cwd, ctx.config);
+            await index.ensureFresh(args.refresh === true ? 0 : 30_000);
+            hits = await index.searchAsync(query, topK);
+            note += index.semanticError
+                ? '（语义检索不可用，已回退关键词检索：' + index.semanticError + '）\n\n'
+                : index.semanticActive
+                    ? '（语义 + 关键词混合检索）\n\n'
+                    : '';
+        }
+        if (hits.length === 0) {
+            return note + '没有找到相关内容。';
+        }
+        return note + hits.map((hit, position) => {
+            const body = hit.text.length > MAX_SNIPPET
+                ? hit.text.slice(0, MAX_SNIPPET) + '\n…'
+                : hit.text;
+            const semantic = hit.semantic === undefined
+                ? ''
+                : ' · 语义 ' + hit.semantic.toFixed(2);
+            return (position + 1) + '. ' + hit.path + ':' + hit.startLine + '-' + hit.endLine
+                + '（相关度 ' + hit.score.toFixed(2) + semantic + '）\n```\n' + body + '\n```';
+        }).join('\n\n');
+    },
+};
+async function remoteSearch(options, query, fallbackTopK) {
+    const headers = { 'content-type': 'application/json' };
+    if (options.apiKey) {
+        headers.authorization = 'Bearer ' + options.apiKey;
+    }
+    const response = await fetch(remoteQueryUrl(options.baseUrl ?? ''), {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ query, top_k: options.topK ?? fallbackTopK }),
+        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_REMOTE_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        const body = (await response.text()).replace(/\s+/g, ' ').trim().slice(0, 200);
+        throw new Error('HTTP ' + response.status + (body.length > 0 ? '：' + body : ''));
+    }
+    const payload = await response.json();
+    const raw = Array.isArray(payload.results)
+        ? payload.results
+        : Array.isArray(payload.hits)
+            ? payload.hits
+            : [];
+    const hits = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object') {
+            continue;
+        }
+        const record = item;
+        const filePath = typeof record.path === 'string'
+            ? record.path
+            : typeof record.file === 'string' ? record.file : '';
+        const text = typeof record.text === 'string'
+            ? record.text
+            : typeof record.content === 'string'
+                ? record.content
+                : typeof record.snippet === 'string' ? record.snippet : '';
+        if (filePath.length === 0 || text.length === 0) {
+            continue;
+        }
+        const startLine = toNumber(record.start_line ?? record.startLine, 1);
+        const endLine = toNumber(record.end_line ?? record.endLine, startLine);
+        const score = typeof record.score === 'number' && Number.isFinite(record.score)
+            ? record.score
+            : 0;
+        hits.push({ path: filePath, startLine, endLine, text, score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, 20);
+}
+function remoteQueryUrl(baseUrl) {
+    const base = baseUrl.replace(/\/+$/, '');
+    if (/\/v1$/i.test(base)) {
+        return base + '/query';
+    }
+    return base + '/v1/query';
+}
+function toNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(1, Math.floor(value))
+        : fallback;
+}