# @esankhan3/anvil-knowledge-core 中文文档 规范地址：https://npmcn.com/package/%40esankhan3/anvil-knowledge-core/ 版本：0\.4\.13 npm 元数据更新时间：2026-11-13T07:42:46.763Z 中文译文更新时间：2026-11-14T06:59:34.702Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40esankhan3/anvil-knowledge-core 原文对照：https://npmcn.com/package/%40esankhan3/anvil-knowledge-core/?lang=original 项目主页：https://github.com/esanmohammad/Anvil/tree/main/packages/knowledge-core#readme 源码仓库：https://github.com/esanmohammad/Anvil ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2 MB，350 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：9 个 - 首次发布：2026-05-05T11:22:12.688Z - 最新版本发布：2026-11-13T07:42:46.375Z - 近 30 天下载量：2182（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：32（近 12 个月 32 个） ## 中文简介 共享知识堆栈(chunking,AST,嵌入器,向量存储,混合检索)用于cli + 代码-搜索-mcp. ## 安装 ```sh npm install @esankhan3/anvil-knowledge-core ``` 也可以使用：`pnpm add @esankhan3/anvil-knowledge-core`、`yarn add @esankhan3/anvil-knowledge-core`、`bun add @esankhan3/anvil-knowledge-core` ## README # @anvil/知识-核心 **你的密码库,可检索.** 代码感知知识堆栈——AST级分解,混合检索, 项目图,和跨repo边缘检测。 特务们看到 页:1 _整体_ 代码库,不只是你碰巧打开的文件. * * * ## Grep + 嵌入的问题 代码搜索有两种方法之一: 词汇法(grep, fast, dumb) 或 基于嵌入的(vector DB,在编辑上缓慢,对结构盲去). 两者 错过相同的东西: 代码有 _图表_ 结构。 一个功能不是 只是一大堆文字——它进口东西,被东西召唤, 执行东西,生活在一个包里, 谈话到其他重置. **知识核心把密码库当成一个图表和一个工具 同时.** 树保姆将每种支持的语言分析为 AST块。 一个向量存储 + BM25 + 一个工程图形全部回答 相同的查询, 连接到一个排序列表中 。 检索者知道什么时候 你在问一个标识符对一个错误代码对一个自然 - 语言问题和相应的信号加权. ```ts import { indexFromPath, getRetriever, loadKnowledgeConfig, } from '@esankhan3/anvil-knowledge-core'; // Build a fully-resolved KnowledgeConfig: YAML at // ~/.anvil/projects//factory.yaml, overlaid by CODE_SEARCH_* // env vars. Or hand-construct one — the indexer accepts any shape. const config = loadKnowledgeConfig('space-tourism'); // Index once — incremental thereafter. Pass config explicitly so // CODE_SEARCH_* env vars (provider, model, dims, API key, base URL) // actually reach the embedder — pre-P1 they were silently ignored. await indexFromPath('space-tourism', '/path/to/workspace', { config }); // Retrieve — vector + BM25 + 1-hop graph + cross-encoder rerank. // Pass the same config so query-time embedder matches the index. // getRetriever() also hard-errors on vector-space mismatch (P2) so // silent provider drift is impossible. const retriever = await getRetriever('space-tourism', config); const result = await retriever.retrieve( 'where do we validate booking seat tiers?', ); console.log(result.chunks.length, 'chunks'); // ranked, deduped console.log(result.graphContext); // related symbols console.log(result.totalTokens); // budgeted ``` * * * ## 你得到的东西 ### AST 认识块 `tree-sitter` WASM 解析类型脚本, JavaScript, TSX, Go, Python, Rust, Java, 和 PHP 进入适当的函数/ 类/ 方法 边框。 不再将一个函数切成两半的块 。 缩写 没有语法的语言倒行逆施,所以没有什么是无索引的. ### 默认递增 索引员读到 `git rev-parse HEAD`,对上一个 索引了SHA, 并且只重装改变的东西。 删除的文件获得 从向量存储中移除。 嵌入是独立的 递增的 —— 它向 LanceDB 传递新的块ID , 并且只有 嵌入三角洲。 大回扣永远保持快. ### 混合检索,四个阶段 1. **BM25 平行向量** ——语义回想+语法回想. 2. **对等排名组合** ——不设一统. 3. **AST 三方扩展** - 召集呼叫者、被呼叫者以及 通过项目图表键入引用. 4. **交叉编码器重新排序** 默认的 Quen3- Ranker; Cohere / Voyage / OpenAI相容可互换. 查询分类员选择适应性权重——识别器精度 BM25,自然语言向量倾斜,出错代码都倾斜. ### 6个嵌入式提供者,4个重排 **内嵌 :** (原始内容存档于2013-10-12) (英语). Codestral / Mistral / Voyage / OpenAI / Ollama 双子座 OAuth (自动刷新已过期的访问符号通过 `refresh_token`· OpenAI 兼容 / 自定义 `auto` (根据配置的选取). **重新排序 :** Ollama (默认) `qwen2.5-coder:7b` qwen3:0.6b是一个 静静无声,然后被放弃) 相机 相机 相机 相机 OpenAI 兼容 . 插入符合成本/质量/纬度曲线的任何内容. ### 明确配置 + 覆盖 `KnowledgeConfig` 是单项合同. `EmbeddingProviderConfig` 带 `{provider, model?, dimensions?, apiKey?, baseUrl?, ollamaHost?}`· ; `RerankerProviderConfig` 带 `{provider, model?, apiKey?, baseUrl?, timeoutMs?}`。 。 。 . `loadKnowledgeConfig(project)` 读取工程 YAML 然后覆盖 `CODE_SEARCH_*` (原始内容存档于2013-10-12) (中文(简体) ). env vars (n`EMBEDDING_PROVIDER` 编号 : `_MODEL` 编号 : `_DIMENSIONS` 编号 : `_API_KEY` 编号 : `_BASE_URL` 编号 : `OLLAMA_HOST` 编号 : `RERANKER_PROVIDER` 编号 : `_MODEL` 编号 : `_API_KEY` 编号 : `_BASE_URL` 编号 : `RETRIEVAL_MAX_CHUNKS` 编号 : `_MAX_TOKENS` 编号 : `AUTO_INDEX`) (中文(简体) ). 提供者 分类仍然读取有文献记载的销售商`MISTRAL_API_KEY`, (中文(简体) ), `OPENAI_API_KEY`,.)作为被贬低的倒计时——每读一读 发出一发一发的 stderr 警告; 库 env 读取在 1.0 中被删除 . ### 矢量空间安全 `getRetriever(project, config?)` 读取每个repo的 `index_meta.json` 打开 如果记录 `embeddingProvider` 和我们不匹配 当前配置, 它扔出一个硬错误 —— 永远不返回垃圾 从一个配置漂移的向量。 (前P2,无声空间不匹配是 canonical "结果无用,没有出错"bug. ) ### 项目图 A 类 `graphology` 指导多图缝合 每回波一起. 节点是实体(函数,类,类型,模块),边缘是 导入 / 调用 / 继承 / 包含 / 类型- refs 。 卢万 社区检测群集相近的代码 可以浮出“认证子系统”而不是四个分散的文件. ### 跨雷波边缘探测 涉及共享类型、卡夫卡专题、HTTP的14个战略 端点, gRPC, 数据库, env vars, npm/工作空间分解, k8s, docker-compose),原生定义,Redis,S3和共享常数. 加上一个LLM-受精语义的边缘层 对于病例的正格克斯不能 抓起来. ### 由LLM驱动,在它重要的地方 回波剖析(指印文件 → LLM → 键入) `RepoProfile`, (中文(简体) ), 由指纹散列缓存),语义边缘推论,项目 汇总生成,RAG质量评价. 所有路由经过 `@anvil/agent-core` 所以,同样的路由器, 重试,和成本分类账 电源 代理堆积 电能知识摄取. ### 结构散列 `computeStructuralHash` 将来源化——去除评论, 折叠出白空间,使标识符正常化 —— SHA-256s 结果。 用于块拆卸 _财务报告和审定财务报表_ 与 `@anvil/memory-core` 所以内存漂移检测 和块分解 说相同的语言. * * * ## 一览建筑 ``` git repo(s) │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Indexing │ │ walk + git diff → tree-sitter chunks → AST graph │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ LanceDB BM25 (FTS) project graph │ │ (vectors) + cross-repo edges │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ HybridRetriever │ │ query classifier ─▶ adaptive weights │ │ vector ⫽ BM25 → RRF → AST expansion → rerank │ └─────────────────────────────────────────────────────────┘ │ ▼ ranked chunks + graph context ``` 两个消费者,一叠: `@esankhan3/anvil-cli` 通过 `anvil index` 在管道中取回; `@esankhan3/code-search-mcp` 曝光与 MCP 相同的检索器 任何代理人都可以调用的工具. * * * ## 存储布局 ``` ~/.anvil/knowledge-base// /chunks.ndjson # the repo's chunks (consumed by embedder) deleted_files.json # incremental embed cleanup system_graph_v2.json # merged project graph PROJECT_GRAPH.json # LLM-generated semantic graph PROJECT_SUMMARY.md # human-readable companion lancedb/ # vector store / profile.json # cached RepoProfile graph.json # per-repo AST graph GRAPH_REPORT.md # quality report index_meta.json # { lastIndexedSha, files, chunkCount } ``` 所有东西都放在磁盘上,可以检查,方便点 感(项目图+摘要). * * * ## 哲学 **春克应该遵循代码形状,而不是字节数.** AST 边界 保持整个函数。 检索质量从块开始. **没有单一的检索信号就足够了.** 矢量丢失标识符 . BM25 错过了解释。 图形错过了文本形状的所有内容 . Hybrid + 适应性加权是唯一诚实的答案. **递增或无.** 每条输油管都有异常指数. 完整的再索引是不可接受的; 引擎处理前一个 SHA作为负载输入. **没有供应商锁定.** 兰斯DB在磁盘上. `graphology` 正在处理中. 可插件嵌入器+再排出. 在不重写的情况下交换任意一层 其余部分. **两个表面,一个引擎.** CLI 用户通过检索 管道; MCP 用户通过工具调用获得. 检索 管道是同一个代码路径. * * * ## 状态 平稳:块、AST图、混合检索、增量 指数化,6个嵌入器,4个复排器,14个交叉复排器 战略,项目图,结构散列. 飞行中:富人 图表查询和更深的RAG-eval带. * * * ## 部分 [安维尔](https://npmcn.com/package/) ——AI开发管道. ## 常见问题 ### @esankhan3/anvil-knowledge-core 是什么？ 共享知识堆栈\(chunking,AST,嵌入器,向量存储,混合检索\)用于cli \+ 代码-搜索-mcp\. ### 如何安装 @esankhan3/anvil-knowledge-core？ 在项目目录运行 npm install @esankhan3/anvil-knowledge-core，或使用 pnpm add / yarn add / bun add。 ### @esankhan3/anvil-knowledge-core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @esankhan3/anvil-knowledge-core 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @esankhan3/anvil-knowledge-core 可以商用吗？ @esankhan3/anvil-knowledge-core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @esankhan3/anvil-knowledge-core 的下载量有多少？ 根据 npm 官方下载统计，@esankhan3/anvil-knowledge-core 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,182 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @esankhan3/anvil-knowledge-core 还在维护吗？ 最新版本 0\.4\.13 发布于 2026/11/13（1 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/05/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。