{"_id":"@anmezing/lce","_rev":"4-40694bfe4448471463b932543ef6519d","name":"@anmezing/lce","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@anmezing/lce","version":"1.0.0","author":{"name":"anmezing"},"license":"MIT","_id":"@anmezing/lce@1.0.0","maintainers":[{"name":"anmezing","email":"qinqingdao@gmail.com"}],"homepage":"https://github.com/anmezing/lce#readme","bugs":{"url":"https://github.com/anmezing/lce/issues"},"bin":{"lce":"dist/index.js"},"dist":{"shasum":"4c2cdcecbaeb7ae5db73e8532df84416a78f2d23","tarball":"https://registry.npmjs.org/@anmezing/lce/-/lce-1.0.0.tgz","fileCount":84,"integrity":"sha512-3ZsoRnqwfp1YPfFx/C0uBCjqGoU5Am3ltLrKyKeG/fhh70qfEYlL7MlQwaDWpz87FpawpuzJdNs/kMyuIZXiZw==","signatures":[{"sig":"MEUCIQCuCKAl57BNX7/Tf+m3gVqsAqF0qg+8lAr4J/l5KgVpTAIgbewJYZ9NwKuSFjsD/67oWpazYuP8WOaAZNZ52/j6Trk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2208367},"type":"module","engines":{"node":">=20"},"gitHead":"0380452c263cf861c9f8393df539ac6ce8d2e995","private":false,"scripts":{"dev":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --watch","fmt":"biome check --write ./src","build":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --clean && node scripts/write-build-info.mjs","mcp:smoke":"vitest run src/mcp/server.smoke.test.ts","build:release":"tsup src/index.ts --format esm --dts --out-dir dist --clean && node scripts/write-build-info.mjs","eval:retrieval":"pnpm build && node dist/index.js eval retrieval --json"},"_npmUser":{"name":"anmezing","email":"qinqingdao@gmail.com"},"repository":{"url":"git+https://github.com/anmezing/lce.git","type":"git"},"_npmVersion":"11.13.0","description":"Local Context Engine for AI coding agents","directories":{},"_nodeVersion":"22.20.0","dependencies":{"cac":"^6.7.14","zod":"^4.2.1","pino":"^10.1.0","dotenv":"^17.2.3","ignore":"^7.0.5","chardet":"^2.1.1","p-limit":"^7.2.0","iconv-lite":"^0.7.1","typescript":"^5.9.3","tree-sitter-c":"^0.24.1","better-sqlite3":"^12.2.0","tree-sitter-go":"0.25.0","tree-sitter-cpp":"^0.23.4","tree-sitter-php":"0.24.2","@lancedb/lancedb":"^0.22.0","onnxruntime-node":"^1.22.0","tree-sitter-java":"0.23.5","tree-sitter-rust":"0.24.0","tree-sitter-scss":"1.0.0","tree-sitter-swift":"0.7.1","tree-sitter-python":"0.25.0","tree-sitter-c-sharp":"^0.23.1","@keqingmoe/tree-sitter":"^0.26.2","tree-sitter-javascript":"0.25.0","tree-sitter-typescript":"0.23.2","@huggingface/transformers":"^3.5.0","@modelcontextprotocol/sdk":"^1.25.1"},"_hasShrinkwrap":false,"devDependencies":{"knip":"^5.78.0","tsup":"^8.5.1","vitest":"^4.1.8","@types/node":"^24.10.4","@biomejs/biome":"2.3.10","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/lce_1.0.0_1786275572526_0.8340625383421514","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This version is deprecated, please upgrade"},"1.0.1":{"name":"@anmezing/lce","version":"1.0.1","author":{"name":"anmezing"},"license":"MIT","_id":"@anmezing/lce@1.0.1","maintainers":[{"name":"anmezing","email":"qinqingdao@gmail.com"}],"homepage":"https://github.com/anmezing/lce#readme","bugs":{"url":"https://github.com/anmezing/lce/issues"},"bin":{"lce":"dist/index.js"},"dist":{"shasum":"aedbd3e4988dd7c5850dffd5a88a1d6cfa6557b5","tarball":"https://registry.npmjs.org/@anmezing/lce/-/lce-1.0.1.tgz","fileCount":84,"integrity":"sha512-7tVPrF27iHalcuMkt6hvlc2oe7MYor7yRe1ht55jvnZo70//YWBFEswgyBRLar4yjtmFVWj0MOjkL2PrBf9lFA==","signatures":[{"sig":"MEYCIQCldGbZIgohW8zgk7+FWDIWSN0snmWGFcmFxa5yJXgk+QIhANjo+cpfxNBj1ZvU6TJD0qqsViTk0bqm+mvSgdAA6DxO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2220057},"type":"module","engines":{"node":">=20"},"gitHead":"8a6162fb99df8b1d4ddd419d93fd5dc942f2ba89","private":false,"scripts":{"dev":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --watch","fmt":"biome check --write ./src","build":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --clean && node scripts/write-build-info.mjs","mcp:smoke":"vitest run src/mcp/server.smoke.test.ts","build:release":"tsup src/index.ts --format esm --dts --out-dir dist --clean && node scripts/write-build-info.mjs","eval:retrieval":"pnpm build && node dist/index.js eval retrieval --json"},"_npmUser":{"name":"anmezing","email":"qinqingdao@gmail.com"},"repository":{"url":"git+https://github.com/anmezing/lce.git","type":"git"},"_npmVersion":"11.13.0","description":"Local Context Engine for AI coding agents","directories":{},"_nodeVersion":"22.20.0","dependencies":{"cac":"^6.7.14","zod":"^4.2.1","pino":"^10.1.0","dotenv":"^17.2.3","ignore":"^7.0.5","chardet":"^2.1.1","p-limit":"^7.2.0","iconv-lite":"^0.7.1","typescript":"^5.9.3","tree-sitter-c":"^0.24.1","better-sqlite3":"^12.2.0","tree-sitter-go":"0.25.0","tree-sitter-cpp":"^0.23.4","tree-sitter-php":"0.24.2","@lancedb/lancedb":"^0.22.0","onnxruntime-node":"^1.22.0","tree-sitter-java":"0.23.5","tree-sitter-rust":"0.24.0","tree-sitter-scss":"1.0.0","tree-sitter-swift":"0.7.1","tree-sitter-python":"0.25.0","tree-sitter-c-sharp":"^0.23.1","@keqingmoe/tree-sitter":"^0.26.2","tree-sitter-javascript":"0.25.0","tree-sitter-typescript":"0.23.2","@huggingface/transformers":"^3.5.0","@modelcontextprotocol/sdk":"^1.25.1"},"_hasShrinkwrap":false,"devDependencies":{"knip":"^5.78.0","tsup":"^8.5.1","vitest":"^4.1.8","@types/node":"^24.10.4","@biomejs/biome":"2.3.10","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/lce_1.0.1_1786276868530_0.2845468315339692","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This version is deprecated, please upgrade"},"1.0.3":{"name":"@anmezing/lce","version":"1.0.3","author":{"name":"anmezing"},"license":"MIT","_id":"@anmezing/lce@1.0.3","maintainers":[{"name":"anmezing","email":"qinqingdao@gmail.com"}],"homepage":"https://github.com/anmezing/lce#readme","bugs":{"url":"https://github.com/anmezing/lce/issues"},"bin":{"lce":"dist/index.js"},"dist":{"shasum":"0698eaefa73e2656fdba12491183f79a60ee5049","tarball":"https://registry.npmjs.org/@anmezing/lce/-/lce-1.0.3.tgz","fileCount":84,"integrity":"sha512-5OQsaOoStjopWE2d/N0DTKQonC+qlfN86jabdaG45avF5PBNT8655kiZVrHbGNqGm5res43dkHq+yzGA/QV12A==","signatures":[{"sig":"MEUCIBBNB4xg6wQ0A7vxcgoYA1QoRcKvoLnLxO4iaWWJ5pUZAiEAmU2ZENcO3UclBFYFhiIq0Y9xU6iMpj384GDZntwix/E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2213102},"type":"module","engines":{"node":">=20"},"gitHead":"dd002f02a2f43702187e3ac6777efd8b52801c74","private":false,"scripts":{"dev":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --watch","fmt":"biome check --write ./src","build":"tsup src/index.ts --format esm --dts --out-dir dist --sourcemap --clean && node scripts/write-build-info.mjs","mcp:smoke":"vitest run src/mcp/server.smoke.test.ts","build:release":"tsup src/index.ts --format esm --dts --out-dir dist --clean && node scripts/write-build-info.mjs","eval:retrieval":"pnpm build && node dist/index.js eval retrieval --json"},"_npmUser":{"name":"anmezing","email":"qinqingdao@gmail.com"},"repository":{"url":"git+https://github.com/anmezing/lce.git","type":"git"},"_npmVersion":"10.8.2","description":"Local Context Engine for AI coding agents","directories":{},"_nodeVersion":"20.20.2","dependencies":{"cac":"^6.7.14","zod":"^4.2.1","pino":"^10.1.0","dotenv":"^17.2.3","ignore":"^7.0.5","chardet":"^2.1.1","p-limit":"^7.2.0","iconv-lite":"^0.7.1","typescript":"^5.9.3","tree-sitter-c":"^0.24.1","better-sqlite3":"^12.2.0","tree-sitter-go":"0.25.0","tree-sitter-cpp":"^0.23.4","tree-sitter-php":"0.24.2","@lancedb/lancedb":"^0.22.0","onnxruntime-node":"^1.22.0","tree-sitter-java":"0.23.5","tree-sitter-rust":"0.24.0","tree-sitter-scss":"1.0.0","tree-sitter-swift":"0.7.1","tree-sitter-python":"0.25.0","tree-sitter-c-sharp":"^0.23.1","@keqingmoe/tree-sitter":"^0.26.2","tree-sitter-javascript":"0.25.0","tree-sitter-typescript":"0.23.2","@huggingface/transformers":"^3.5.0","@modelcontextprotocol/sdk":"^1.25.1"},"_hasShrinkwrap":false,"devDependencies":{"knip":"^5.78.0","tsup":"^8.5.1","vitest":"^4.1.8","@types/node":"^24.10.4","@biomejs/biome":"2.3.10","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/lce_1.0.3_1786292818938_0.4290362004251129","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This version is deprecated, please upgrade"}},"time":{"created":"2026-08-09T11:39:32.278Z","modified":"2026-08-10T01:42:34.064Z","1.0.0":"2026-08-09T11:39:32.676Z","1.0.1":"2026-08-09T12:01:08.705Z","1.0.3":"2026-08-09T16:26:59.093Z"},"bugs":{"url":"https://github.com/anmezing/lce/issues"},"author":{"name":"anmezing"},"license":"MIT","homepage":"https://github.com/anmezing/lce#readme","repository":{"url":"git+https://github.com/anmezing/lce.git","type":"git"},"description":"Local Context Engine for AI coding agents","maintainers":[{"name":"anmezing","email":"qinqingdao@gmail.com"}],"readme":"# LCE\n\n语言：简体中文 | [English](README.en.md)\n\nLCE 是一个给 AI 编码 agent 使用的代码上下文引擎。它把你的代码库索引到本机存储里，使用 Embedding + Reranker 做语义检索，通过 CLI 或 MCP Server 返回相关代码片段、文件路径、行号范围、Git 上下文和 freshness 诊断。索引与存储始终在本机。\n\n开箱即用：默认使用内置 ONNX 模型（首次检索时自动下载），零配置即可开始语义检索。如需更高质量，可切换到云端 API 或自部署的 OpenAI 兼容模型。\n\n<p align=\"center\">\n  <img src=\"docs/architecture.svg\" alt=\"LCE architecture overview\" width=\"800\" />\n</p>\n\n## 它能做什么\n\n- 为单个代码库或显式配置的多根 workspace 建立本地索引。\n- 默认使用内置 ONNX 模型做 semantic/vector 检索与重排，零配置可用；也可切换到云端 API 或自部署的 OpenAI 兼容模型（`EMBEDDINGS_*` / `RERANK_*`）。\n- 离线 / 数据不出网时，使用内置 ONNX 模型或把 provider 指向局域网/localhost 自部署模型即可。exact/lexical/符号图作为召回通道参与语义检索，并在 provider 临时失败时兜底。\n- 提供 MCP Server，包含代码检索、符号图、只读 Git 上下文和变更 review 上下文工具。\n- 标记返回上下文是 fresh、stale、missing、partial，还是来自本地 worktree overlay evidence。\n- 把索引、日志、队列和 shared-index cache 存放在 LCE storage root 下，而不是写入源码文件。\n\n## 什么时候该用它\n\n适合用在这些场景：\n\n- 让 AI agent找某个行为在哪里实现。\n- 修改代码前先收集周边上下文。\n- 在不改动仓库的前提下查看本地分支或 review 上下文。\n- 通过显式 workspace config 搜索多个相关仓库。\n- 把已校验的 shared-index snapshot 作为只读上下文来源复用。\n\n不适合把它当作：\n\n- 托管搜索服务或 SaaS 索引。\n- PR bot、webhook 服务、issue commenter 或 CI approval 系统。\n- 完整或权威的 compiler/LSP 符号图（LCE 的符号图是有界本地分析，对 supported 语言用 LSP 后端解析、其余用 tree-sitter，但不是全量 compiler 真值）。\n- bug 根因或完整影响面的保证。\n- 测试、类型检查或人工代码审查的替代品。\n\n## 5 分钟快速开始\n\n安装：\n\n```bash\nnpm install -g @anmezing/lce\n```\n\n初始化配置（交互式向导，支持 `--lang en` 切换英文）：\n\n```bash\nlce init\n```\n\n向导提供三种模式：\n1. **内置模型（默认推荐）** — 零配置，首次检索自动下载 ONNX 模型\n2. **在线 API** — 需要 API Key（SiliconFlow / Voyage / OpenAI 兼容）\n3. **自部署模型** — 局域网/localhost OpenAI 兼容服务（Ollama 等）\n\n选择内置模型后无需任何额外配置即可开始使用。如需完整配置模板，运行 `lce init --template`。\n\n把 MCP server 加到你的 AI 客户端配置里：\n\n```json\n{\n  \"mcpServers\": {\n    \"lce\": {\n      \"command\": \"lce\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n重启或刷新 MCP client 后，AI agent会通过 MCP `tools/list` 看到 LCE 的工具。你不需要手写 `codebase-retrieval` 参数；正常使用时直接让 agent 理解项目、查找实现、分析变更或收集修改前上下文即可。\n\n验证本机安装和索引状态：\n\n```bash\nlce doctor --repo . --mcp\nlce status --repo .\n```\n\n如果你想在不接 MCP 的情况下手动验证检索，可以使用 CLI search：\n\n```bash\nlce search --information-request \"Where is configuration loaded?\" --freshness-policy fresh-local-blocking\n```\n\nCLI search 是调试/验证入口，不是普通 MCP 用户的主工作流。\n\n## 安装\n\n全局安装：\n\n```bash\nnpm install -g @anmezing/lce\n```\n\n这个包暴露一个主命令：\n\n```bash\nlce --version\n```\n\n从源码运行：\n\n```bash\npnpm install\npnpm build\nnode dist/index.js --version\n```\n\n`package.json` 里当前可用的开发脚本包括 `pnpm build`、`pnpm build:release`、`pnpm dev`、`pnpm eval:retrieval`、`pnpm fmt` 和 `pnpm mcp:smoke`。\n\n## 配置\n\n`lce init` 会在当前 storage root 里创建 `.env` 文件。默认 storage root 是系统原生应用数据目录：\n\n- Windows：`%LOCALAPPDATA%\\LCE`\n- macOS：`~/Library/Application Support/LCE`\n- Linux：`$XDG_DATA_HOME/lce` 或 `~/.local/share/lce`\n\n可以用 `LCE_HOME` 覆盖 storage root：\n\n```bash\nLCE_HOME=/data/lce lce doctor\n```\n\nPowerShell：\n\n```powershell\n$env:LCE_HOME = 'D:\\LCEData'\nlce doctor\n```\n\n<!-- LCE-env-example:start -->\n```bash\n# ═══════════════════════════════════════════════════════════════════\n# 内置模型（零配置，首次使用时自动下载 ~33MB embedding + ~571MB reranker 模型）\n# 只需设置下面两行即可开始使用语义检索，无需 API Key / Base URL / 模型名。\nEMBEDDINGS_PROVIDER=onnx\nRERANK_PROVIDER=onnx\n# ═══════════════════════════════════════════════════════════════════\n\n# Embedding 配置（检索必需：未配置时 lce search 与 MCP 检索会返回引导配置的错误）\n# 使用在线 API 或自部署模型时，将上方 EMBEDDINGS_PROVIDER=onnx 注释掉，取消下方注释。\n# 推荐选用「代码专用」embedding 模型（见下方 Voyage voyage-code-3 示例）。\n# 通用多语言模型（如 bge-m3）在代码检索上明显偏弱，代码专用模型可显著提升召回质量。\n# EMBEDDINGS_API_KEY=your-api-key-here\n# EMBEDDINGS_BASE_URL=https://api.siliconflow.cn/v1/embeddings\n# EMBEDDINGS_MODEL=BAAI/bge-m3\n# EMBEDDINGS_MAX_CONCURRENCY=10\n# EMBEDDINGS_TIMEOUT_MS=30000\n# 日 token 预算：默认「咨询式」——如实记录并在超过时告警，但不阻断调用。\n# 需要硬性花费上限（超额即停）时，取消下一行注释设为 true（付费 API 场景）。\n# EMBEDDINGS_DAILY_TOKEN_BUDGET=1000000\n# EMBEDDINGS_DAILY_TOKEN_BUDGET_ENFORCE=true\n# EMBEDDINGS_DIMENSIONS=1024\n\n# Voyage example（voyage-code-3 = 推荐的代码专用 embedding）:\n# EMBEDDINGS_PROVIDER=voyage\n# EMBEDDINGS_BASE_URL=https://api.voyageai.com/v1/embeddings\n# EMBEDDINGS_MODEL=voyage-code-3\n# EMBEDDINGS_DIMENSIONS=1024\n# EMBEDDINGS_OUTPUT_DIMENSION=1024\n# EMBEDDINGS_OUTPUT_DTYPE=float\n\n# 自部署 embedding（局域网/localhost，离线场景推荐；OpenAI 兼容：Ollama / vLLM / LM Studio / localai）:\n# EMBEDDINGS_PROVIDER=openai-compatible\n# EMBEDDINGS_BASE_URL=http://localhost:11434/v1/embeddings\n# EMBEDDINGS_MODEL=nomic-embed-text\n# EMBEDDINGS_API_KEY=dummy\n# EMBEDDINGS_DIMENSIONS=768\n# Instruction prefixes for asymmetric retrieval models (openai-compatible only; trailing space matters):\n# nomic-embed-text: EMBEDDINGS_QUERY_PREFIX / EMBEDDINGS_DOCUMENT_PREFIX below\n# BGE (bge-large/base): use \"query: \" and \"passage: \"\n# EMBEDDINGS_QUERY_PREFIX=search_query:\n# EMBEDDINGS_DOCUMENT_PREFIX=search_document:\n\n# Reranker 配置（使用在线 API 时，将上方 RERANK_PROVIDER=onnx 注释掉，取消下方注释）\n# RERANK_API_KEY=your-api-key-here\n# RERANK_BASE_URL=https://api.siliconflow.cn/v1/rerank\n# RERANK_MODEL=BAAI/bge-reranker-v2-m3\n# RERANK_TOP_N=20\n# RERANK_TIMEOUT_MS=15000\n# Reranker provider（可选，默认 siliconflow-compatible）\n# RERANK_PROVIDER=siliconflow-compatible\n\n# Voyage reranker example:\n# RERANK_PROVIDER=voyage\n# RERANK_BASE_URL=https://api.voyageai.com/v1/rerank\n# RERANK_MODEL=rerank-2.5\n# RERANK_MODEL=rerank-2.5-lite\n\n# Custom/local SiliconFlow-compatible reranker example:\n# RERANK_PROVIDER=custom\n# RERANK_BASE_URL=http://localhost:8000/v1/rerank\n# RERANK_MODEL=BAAI/bge-reranker-v2-m3\n# RERANK_MODEL=Qwen/Qwen3-Reranker-0.6B\n# RERANK_API_KEY=dummy\n# RERANK_TOP_N=20\n\n# 忽略模式（可选，逗号分隔）\n# IGNORE_PATTERNS=.venv,node_modules\n\n# MCP server semantic auto-index（可选）\n# auto: valid EMBEDDINGS_* enables semantic auto-index; persistent HTTP starts/reuses worker/watcher, short-lived stdio queues only\n# false: disable server default auto-index; clients may still request live_context.auto_index explicitly\n# INDEX_AUTO_SEMANTIC=auto\n# INDEX_AUTO_SEMANTIC_MAX_REPOS=3\n```\n<!-- LCE-env-example:end -->\n\n真实环境变量见 [docs/configuration.md](docs/configuration.md)。主要 key 如下：\n\n| 类型 | Keys |\n| --- | --- |\n| Storage | `LCE_HOME` |\n| Embedding | `EMBEDDINGS_API_KEY`, `EMBEDDINGS_BASE_URL`, `EMBEDDINGS_MODEL`, `EMBEDDINGS_MAX_CONCURRENCY`, `EMBEDDINGS_TIMEOUT_MS`, `EMBEDDINGS_DAILY_TOKEN_BUDGET`, `EMBEDDINGS_DAILY_TOKEN_BUDGET_ENFORCE`, `EMBEDDINGS_DIMENSIONS`, `EMBEDDINGS_PROVIDER`, `EMBEDDINGS_OUTPUT_DIMENSION`, `EMBEDDINGS_OUTPUT_DTYPE` |\n| Rerank | `RERANK_API_KEY`, `RERANK_BASE_URL`, `RERANK_MODEL`, `RERANK_TOP_N`, `RERANK_TIMEOUT_MS`, `RERANK_PROVIDER` |\n| Scanner | `IGNORE_PATTERNS` |\n| Indexing | `INDEX_AUTO_SEMANTIC`, `INDEX_AUTO_SEMANTIC_MAX_REPOS` |\n\n**推荐的默认用法**是配置 `EMBEDDINGS_*` + `RERANK_*`：semantic 索引、semantic query 与 rerank 精排随之可用。MCP server 在 `EMBEDDINGS_*` 有效时启用 repo-path semantic auto-index；持久的 HTTP server 默认启动/复用 worker 与 watcher，短生命周期的 stdio `lce mcp` 默认只排队刷新任务，不在查询进程内启动长期后台组件。需要处理队列时运行 `lce index worker --daemon --mode semantic --profile semantic`（local 队列可用 `--mode local --profile interactive`）。`INDEX_AUTO_SEMANTIC=false` 可关闭 server 默认行为，`INDEX_AUTO_SEMANTIC_MAX_REPOS` 控制最多同时覆盖多少个 repo。**embedding 是检索的必需项**：未配置时 `lce search` 与 MCP 检索直接返回引导配置的错误；离线场景把 provider 指向局域网或 localhost 上自部署的本地模型即可。\n\n### 使用本地模型（自部署 Embedding / Rerank）\n\nprovider 只认 base URL，指向局域网或 localhost 的 OpenAI 兼容端点即可，无需云端 API。**这是离线 / 不希望数据出网用户的推荐路径**——检索质量口径仍是语义检索，只是数据边界留在本机：\n\n- **Embedding**：`EMBEDDINGS_PROVIDER=openai-compatible`，`EMBEDDINGS_BASE_URL` 指向本地服务（Ollama `http://localhost:11434/v1/embeddings`、vLLM、LM Studio、localai 等），`EMBEDDINGS_MODEL` 填本地模型名，`EMBEDDINGS_DIMENSIONS` 必须与模型输出维度一致；本地服务不校验鉴权时 `EMBEDDINGS_API_KEY` 填任意占位值（如 `dummy`）。\n- **Rerank**：`RERANK_PROVIDER=custom`（或 `siliconflow-compatible`），`RERANK_BASE_URL` 指向本地 rerank 服务（如 `http://localhost:8000/v1/rerank`）。\n\n`.env` 模板（上方 `lce init` 生成的示例块）已内置 Ollama embedding 与本地 rerank 的注释示例，取消注释并按你的本地服务调整即可。\n\n## 常用命令\n\n| 命令 | 用途 | 写入范围 |\n| --- | --- | --- |\n| `lce init` | 创建 storage root 和 `.env` 模板 | 仅 storage |\n| `lce status --repo .` | 查看本地索引状态 | 不写入 |\n| `lce doctor --repo . --mcp` | 检查环境、storage、index 和 MCP 定义 | 不写入 |\n| `lce mcp` | 通过 stdio 启动 MCP Server，供 AI 客户端调用 | 不写源码；可能写 storage index/queue |\n| `lce search --information-request \"...\"` | 手动验证/调试本地检索；MCP 用户通常不需要直接调用 | 可能排入本地刷新 job |\n| `lce index .` | 扫描并索引 repo，启用 vector indexing | storage；可能调用 embedding API |\n| `lce index jobs --json` | 查看异步索引 job | 不写入 |\n| `lce storage status --json` | 查看 storage 使用量和迁移状态 | 不写入 |\n| `lce mcp --transport http --host 127.0.0.1 --port 3000 --path /mcp` | 显式启动 experimental Streamable HTTP MCP Server | 不写入 |\n\n更多 CLI 细节见 [docs/configuration.md](docs/configuration.md)、[docs/workspace.md](docs/workspace.md)、[docs/git-context.md](docs/git-context.md) 和 [docs/troubleshooting.md](docs/troubleshooting.md)。\n\nMCP server 启动本身不会立刻扫描所有项目。AI agent调用 repo-path 检索工具时，LCE 会按当前配置检查/刷新索引；如果 `EMBEDDINGS_*` 有效且 `INDEX_AUTO_SEMANTIC` 未禁用，持久 HTTP server 会启动或复用受资源上限保护的 semantic worker/watcher lifecycle，而一次性 stdio server 只把刷新任务写入队列并在 freshness 输出中提示 daemon 命令，避免进程退出留下僵尸任务。默认最多同时覆盖 3 个 repo，可用 `INDEX_AUTO_SEMANTIC_MAX_REPOS` 调整；设置 `INDEX_AUTO_SEMANTIC=false` 可关闭 server 默认自动 semantic 索引。显式请求 `live_context.auto_index.start_worker=true` 仍可按请求启动 worker。\n\n## MCP 使用方式\n\n普通用户通常只需要把下面的 MCP 配置加入 AI 客户端。客户端会启动 `lce mcp`，agent 会通过 MCP schema 自己选择工具和参数。\n\nMCP client 配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"lce\": {\n      \"command\": \"lce\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n手动启动 stdio server 主要用于排错：\n\n```bash\nlce mcp\n```\n\nStreamable HTTP 仍是显式开启的 experimental transport。默认只监听 localhost，并带 request body、timeout、并发请求、session 上限和 idle session TTL。绑定非 loopback 地址（例如 `0.0.0.0`）必须额外传 `--allow-remote`；HTTP transport 不内置认证，远程暴露时必须放在带鉴权的反代或等价网络控制后面：\n\n```bash\nlce mcp --transport http --host 127.0.0.1 --port 3000 --path /mcp\n```\n\nagent 可见的 MCP tools：\n\n| Tool | 用途 |\n| --- | --- |\n| `codebase-retrieval` | 搜索 repo 或 workspace 上下文，并可返回 context pack 或 context bundle。 |\n| `codebase_symbol_graph` | 查询本地符号图证据，包括 definitions、references、callers、callees、importers、tests 和 bounded impact。 |\n| `codebase_git_context` | 执行受控的只读 Git 上下文模式，例如 status、diff、history、blame、branch context 和 change review。 |\n| `codebase_review_changes` | 组合只读 change review 证据、retrieval plan 和 test plan；真正执行 retrieval 需要显式 opt-in。 |\n\n`codebase_review_changes` 默认不运行 retrieval，默认不运行测试，默认不触发 indexing，默认不调用 embedding / rerank / API；只有显式设置 `include_retrieval=true` 才会进入检索路径。\n\n完整 MCP 参数和 JSON 示例见 [docs/mcp.md](docs/mcp.md)。\n\nMCP 可见性 smoke 可以按这四项排查：\n\n- Source registered：MCP client 已注册 `lce` source。\n- Dist built：已运行 `pnpm build` 或安装了最新包。\n- MCP server running：`lce mcp` 能通过 stdio 启动；HTTP 模式用 `lce mcp --transport http --host 127.0.0.1 --port 3000 --path /mcp` 显式启动。\n- Client visible：MCP client 能列出并调用 LCE tools。\n\n`doctor --mcp` 是静态检查，不会证明 MCP client 已经加载新 server；端到端 smoke 用：\n\n```bash\npnpm run mcp:smoke\n```\n\n## 常见工作流\n\n普通 MCP 用户可以直接向 AI agent提出这类请求：\n\n- “先用 LCE 理解这个项目的架构，再给我改动计划。”\n- “查一下登录流程在哪里实现，修改前先收集相关上下文。”\n- “审查当前分支改动，重点看配置、索引和 MCP 边界。”\n- “这个测试失败可能和哪些文件有关？先找证据，不要直接猜根因。”\n\nagent 会根据 MCP tool description 选择 `codebase-retrieval`、`codebase_git_context`、`codebase_symbol_graph` 或 `codebase_review_changes`。项目理解、架构问题、修改前上下文和 test failure 场景通常会走 `codebase-retrieval` 的 context bundle / workflow 输出；具体参数由 agent 填写。\n\n手动 CLI 适合用来验证或排错：\n\n```bash\nlce search --information-request \"Where is request validation implemented?\" --freshness-policy fresh-local-blocking\nlce index . --force\nlce index jobs --json\n```\n\nWorkspace 需要显式配置文件，不会自动扫描父目录：\n\n```bash\nlce index --workspace-config ./lce.workspace.json\n```\n\n如果你的 MCP client 支持显式 tool call，workspace 检索应传 `workspace_config_path`；详细 JSON 示例见 [docs/mcp.md](docs/mcp.md)。\n\nShared-index snapshot 可用于复用已校验的只读索引：\n\n```bash\nlce index export --repo . --output ./lce-shared-index\nlce index verify-snapshot --input ./lce-shared-index\n```\n\n详细 CLI 和 MCP JSON 示例见 [docs/mcp.md](docs/mcp.md)、[docs/workspace.md](docs/workspace.md) 和 [docs/troubleshooting.md](docs/troubleshooting.md)。\n\n## 常见问题排查\n\n先运行：\n\n```bash\nlce doctor --repo . --mcp\nlce storage status --json\nlce index status --repo . --json\n```\n\n常见处理方式：\n\n- 如果 AI agent提示本地索引 missing 或 stale，可以先运行 `lce index .` 手动建立/刷新当前 repo 索引；未配置 `EMBEDDINGS_*` 时仍可使用本地 exact / lexical 检索。\n- 如果 semantic/vector 索引失败，检查 `EMBEDDINGS_*`，以及 embedding 维度是否和 provider 返回一致。\n- 如果 rerank 失败，检索可以 fallback 到 rerank 前的 candidates；依赖 rerank 前先检查 `RERANK_*`。\n- 如果 workspace root 缺失，检查 workspace config 文件里的路径。\n- 如果 shared-index fetch 或 verification 失败，查看 JSON 输出里的 checksum、schema、path traversal 和 artifact leak 失败信息。\n\n更多情况见 [docs/troubleshooting.md](docs/troubleshooting.md)。\n\n## 数据存放在哪里 / 安全边界\n\nLCE 自己的数据存放在 storage root 下：\n\n| 路径 | 用途 |\n| --- | --- |\n| `.env` | LCE 配置文件，保存 embedding/rerank provider、预算、索引默认行为等环境变量。 |\n| `logs/` | 日志目录，默认写入 `app.YYYY-MM-DD.log`。 |\n| `index-jobs.db` | 异步索引队列数据库，用于 worker/watcher/auto-index 生命周期。 |\n| `<projectId>/` | 单个 repo 或 workspace 的 project 数据目录。`projectId` 根据 repo/workspace canonical path 生成。 |\n| `<projectId>/index.db` | 当前 project 的 SQLite/FTS/exact 本地索引和元数据。 |\n| `<projectId>/vectors.lance/` | 当前 project 的 LanceDB vector store，保存 semantic/vector 索引。 |\n| `<projectId>/project.json` | 当前 project 的 metadata，包括 repo root、workspace roots、schema version 等。 |\n| `shared-indexes/` | 导入或管理的 shared-index snapshot 存放区。 |\n| `shared-index-cache/` | 显式 fetch/refresh 后通过校验的 remote/static shared-index cache。 |\n| `eval-cache/external-golden/` | external golden eval 的 repo/index cache；只在显式运行 external golden eval 时使用。 |\n\nstorage root 默认按操作系统选择：\n\n| 系统 | 默认 storage root |\n| --- | --- |\n| Windows | `%LOCALAPPDATA%\\LCE` |\n| macOS | `~/Library/Application Support/LCE` |\n| Linux | `$XDG_DATA_HOME/lce` 或 `~/.local/share/lce` |\n\n这些默认目录使用 LCE 命名；也可以直接通过 `LCE_HOME` 指到你自己的 LCE 数据目录。\n\n可以用 `LCE_HOME` 统一改到其它位置。这个变量会同时影响 `.env`、日志、索引库、vector store、异步索引队列、shared-index cache、MCP server registry 和默认 eval cache：\n\n```bash\nLCE_HOME=/data/lce lce doctor --repo .\n```\n\nPowerShell：\n\n```powershell\n$env:LCE_HOME = 'D:\\LCEData'\nlce doctor --repo .\n```\n\n可以单独指定的路径：\n\n- external golden eval cache：`lce eval retrieval --external-golden-run --external-golden-cache-dir <path>`\n- MCP client registry：默认是 `LCE_HOME/mcp-servers.json`，相关 `mcp-client` 命令支持 `--registry <path>`\n- shared-index snapshot export / import / verify 的输入输出路径由命令参数显式指定\n\n目前不能单独指定的内部路径：\n\n- 单个 repo 的 `index.db`\n- 单个 repo 的 `vectors.lance/`\n- `index-jobs.db`\n- `logs/`\n- `shared-index-cache/`\n\n如果你想把这些内部索引和缓存整体放到别的磁盘或目录，使用 `LCE_HOME`。query embedding cache 和 graph cache 是进程内缓存，不会写成单独的磁盘缓存目录。\n\n日志写在 `LCE_HOME/logs/app.YYYY-MM-DD.log`，按天分文件追加。当前没有后台自动删除或按大小自动轮转机制；如果从不清理，日志目录会持续增长。可以显式清理旧日志：\n\n```bash\nlce cleanup --old-logs --dry-run\nlce cleanup --old-logs --yes\n```\n\n`--old-logs` 默认选择 7 天以前的日志；可以用 `--older-than <days>` 改保留天数。`cleanup` 默认是 dry-run，只有加 `--yes` 才会删除。\n\n旧索引不会被后台自动删除。比如 repo 被移动/删除、workspace root 不再存在，或你切换了 `LCE_HOME`，旧的 `<projectId>/` 目录会留在原 storage root 中，直到你显式清理。先查看 storage 和候选项：\n\n```bash\nlce storage status --json\nlce cleanup --orphans --dry-run\nlce cleanup --metadata-missing --dry-run\n```\n\n确认 dry-run 输出后再删除：\n\n```bash\nlce cleanup --orphans --yes\nlce cleanup --metadata-missing --yes\n```\n\n如果你明确知道某个 project id，也可以用 `lce cleanup --project <projectId> --dry-run` 先预览，再加 `--yes` 删除。`lce index . --force` 只会重建当前 repo 的索引，不会清理其它旧 project 目录。\n\n普通 indexing 和 search 不会写源码文件。会写 repo 的命令是 `lce hooks install/uninstall`，它会编辑选定 `.git/hooks` 文件里的 managed block。snapshot export 和 publish 会写入你显式提供的 output path。\n\nMCP Git tools 是只读的，不会运行 `fetch`、`pull`、`push`、`checkout`、`reset`、`add` 或 `commit`。外部网络调用只发生在确实需要的路径：embedding/rerank provider、显式 remote snapshot fetch/refresh，或 request-scoped GitHub/web-doc connector config。已配置的 GitHub/web-doc connector 默认启用；如果不想使用某个 connector，把对应配置移除或设为 `enabled=false`。connector 请求会在 `apiCost` / `externalCalls` 和 bundle `freshness` / pipeline trace 中报告。\n\n## 功能限制\n\n- local exact/lexical 结果取决于当前本地索引。\n- semantic 结果取决于 embedding 配置和维度；rerank 取决于 rerank provider 配置。\n- workspace mode 需要显式 JSON config；它不会自动扫描父目录。\n- symbol graph 和 branch inference 是有界本地分析，不是完整 compiler truth。\n- `codebase_review_changes` 本身不运行测试。\n- 未支持的 external connector type 会报告 unsupported，而不是生成证据。\n\n## 开发者文档入口\n\n- [MCP tools](docs/mcp.md)\n- [Configuration](docs/configuration.md)\n- [Workspace config](docs/workspace.md)\n- [Git context](docs/git-context.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Retrieval internals](docs/internals/retrieval.md)\n- [Contract matrix](docs/contract-matrix.md)\n\n## License\n\nMIT\n\n","readmeFilename":"README.md"}