v0ropaev/knowbase

knowbase 将 git 仓库转化为一个**知识层**：一个可查询、受 git 版本控制的模型，用于表达代码库的*含义*——包括其架构、领域实体、API 契约、依赖项、事件和业务流程——其中**每个事实都绑定到它所来源的确切代码行**（`file:line@sha`）。 让它与众不同的是：它不会嵌入你的代码并心存侥幸。它会**提取**持久化的知识，并将每个单元锚定在真实的代码跨度上。LLM 和 embedding 只是围绕这一核心骨架的可*替换适配器*——更换模型，知识及其来源保持不变。 ``` %%{init: {'theme':'base','themeVariables':{'background':'#FAF3E7','primaryColor':'#FAF3E7','primaryTextColor':'#071812','primaryBorderColor':'#1C4434','lineColor':'#3C5B4E','secondaryColor':'#EDE3D2','tertiaryColor':'#F3EAD9','textColor':'#1C4434','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart LR subgraph usual["The usual pipeline — lossy, opaque"] direction LR R1[Repository] --> E1["Embeddings
chunks, no provenance,
drifts from HEAD"] --> A1[AI Agent] end subgraph kbflow["knowbase — grounded, versioned"] direction LR R2[Repository] --> X2["Knowledge Extraction
deterministic + LLM adapters"] --> K2["Knowledge Layer
provenance · method ·
confidence · freshness"] --> A2[AI Agent] end ``` ## 为什么 - **代码只是实现，不是知识。**“API 契约是什么？”、“哪个模块负责计费？”、“什么会使这个缓存失效？”——这些问题无法通过阅读单个文件来回答——答案散布在整个仓库中，且不存在于任何人的脑海中。 - **文档会过时。**手写的架构文档和图表在合并的那一刻起就开始偏离 `HEAD`。由于缺少与代码的机械联系，没有任何东西能告诉你它们何时变得陈旧。 - **Agent 只能得到碎片。**基于代码的 RAG 检索到的是没有来源信息的最近邻块，且无法判断它们是否仍然反映当前的 commit。模型只能靠猜测来填补空白。 knowbase 使用**针对 git 进行版本控制且可追溯到源码的知识单元**来回答——否则干脆不予回答。 ## 工作原理 — 来源骨架 核心不变量：**除非绑定到 ≥ 1 个确切的代码跨度**（`file:line@sha`），否则不会存储任何内容。这条单一规则同时带来了三个特性： - **反幻觉。**未锚定的 artifact *不会被存储*——这在应用内（在任何写入前抛出 `GroundingError`）和数据库中（在 `COMMIT` 时导致事务失败的延迟 `artifact_grounded_check` 约束触发器）都得到了强制执行。一个无法指向代码的 extractor 无法持久化任何声明。 - **增量更新。**`git diff` 将更改的代码映射到更改的跨度，从而*精确地*使那些锚定位置发生移动的派生 artifact 失效——没有过度失效，也没有陈旧的幸存者。 - **消费者信任。**每个提供的单元都包含其来源、产生它的方法（确定性 vs 模型）、置信度以及相对于 commit 的新鲜度。 标识在结构上是**内容寻址且与位置无关的**。一个跨度的 `span_id` 是基于 `(normalization_version, lang, span_kind, fq_symbol_path, structural_fingerprint)` 的 `sha256` 哈希——不包含文件路径，也不包含字节偏移量。结构指纹是 tree-sitter 解析树的标准化 S-表达式（仅包含命名节点；剔除注释*和* docstring；保留标识符和字面量）。因此，重新格式化、移动文件或编辑注释**不会**改变标识；而真正的重命名或结构性编辑则会改变标识。位置按 SHA 记录在 `span_occurrence` 中，与标识分开。 Artifact 以相同的方式进行内容寻址——基于按字节排序、去重后的锚定跨度，加上 `extractor_id`/`extractor_version`（对于基于模型的 extractor，还有 `prompt_version`/`model_id`）。对同一个 commit 重新索引会重现完全相同的 artifact id 集合。 骨架由少量内容寻址的表组成：每个 **artifact** 携带 ≥ 1 条指向 **code_span** 的 `derived_from` 边，跨度按 SHA 记录在 `span_occurrence` 中，而按 SHA 划分的 **snapshot** 将锚定的 artifact 绑定到一个 commit。 ``` %%{init: {'theme':'base','themeVariables':{'background':'#FAF3E7','primaryColor':'#FAF3E7','primaryTextColor':'#071812','primaryBorderColor':'#1C4434','lineColor':'#3C5B4E','secondaryColor':'#EDE3D2','tertiaryColor':'#F3EAD9','textColor':'#1C4434','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart TD AR["artifact
knowledge unit (+ embedding)"] CS["code_span
content-addressed id · location-free"] SO["span_occurrence
file:line @ sha"] SE["snapshot_entry
per-SHA manifest"] CM["commit_ref / branch_ref"] AR -->|"derived_from ≥1 (else rejected:
GroundingError + DB trigger)"| CS CS -->|"located per-SHA"| SO AR -->|"appears in"| SE SE -->|"scoped to"| CM ``` 索引一个 commit 会从头到尾遍历这条骨架——`INGEST → STRUCTURE → INVALIDATE → EXTRACT → SNAPSHOT → SERVE`，而 `kb embed` 作为单独的通道，在此基础之上添加 pgvector 语义搜索： ``` %%{init: {'theme':'base','themeVariables':{'background':'#FAF3E7','primaryColor':'#FAF3E7','primaryTextColor':'#071812','primaryBorderColor':'#1C4434','lineColor':'#3C5B4E','secondaryColor':'#EDE3D2','tertiaryColor':'#F3EAD9','textColor':'#1C4434','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart LR G["git blobs @ SHA
no checkout"] --> S["tree-sitter spans
content-addressed identity"] S --> I["invalidate
diff-based"] I --> X["extractors
deterministic · each grounded ≥1 span"] X --> N["per-SHA snapshot
manifest of grounded artifacts"] N --> EV["eval gate"] EV --> SV["serve
humans + AI agents (MCP)"] N -. "kb embed (separate pass)" .-> EM["pgvector embeddings
semantic search"] EM -.-> SV ``` ## 状态 **v0.3 — 骨架、确定性知识 extractor（支持跨文件锚定）、MCP 服务、知识 vs RAG 的闸门，以及已发布的 Docker 镜像。**这里的每一样东西都为其声明提供了锚定依据，而不提供无法被锚定的内容： - **来源骨架** — 内容寻址的 `span_id`（已锁定）；基于 tree-sitter 的跨度，具有标准化 S-表达式指纹和按 SHA 划分的位置；由 Alembic 管理的单一 Postgres 存储，支持内容寻址的幂等写入；≥ 1 个 `derived_from` 的反幻觉不变量在应用内*以及*由数据库延迟触发器强制执行；带有基于 diff 的失效种子的 pygit2 git 摄取（无需 checkout）。 - **确定性 extractor** — **import / 依赖图**（grimp 解析边，tree-sitter 将其锚定在确切的 import 语句上，对于重导出 / 相对导入 / 无法映射的导入提供诚实的 `approximate` 回退——绝不静默丢失）；**FastAPI API 契约** extractor，它**跨文件**锚定单个路由（`routes.py` 中的 handler + `schemas.py` 中的 `response_model` 类）；**领域实体** extractor（pydantic / dataclass / SQLAlchemy 类及其字段，锚定在类定义上**并跨文件锚定到它们引用的实体**——纯静态，并记录了已知的检测限制）；以及**库公共 API 表面** extractor（一个包从其 `__init__.py` 导出的内容——以 `__all__` 为准，`__init__` 重导出**跨文件**解析到定义它们的函数/类——已通过独立的 **griffe** 静态 ground truth 验证）。 - **`kb introspect`** — 沙盒化、网络隔离的 `app.openapi()` ground truth，仅用于评估，绝不会出现在索引路径中，作为 API 闸门为静态契约打分的基础。 - **只读 MCP 服务器** — `find_provenance`、`get_knowledge` 和 `search_knowledge`，每个都返回带有来源信息的单元（方法 + 置信度 + 新鲜度）。 - **pgvector embedding + 语义搜索** — 可替换的 embedding 提供者（默认为 sentence-transformers，可选 OpenAI）由单独的 `kb embed` 通道填充；torch 不会出现在索引路径中。 - **冻结的基于源码的 RAG 基准**和 **Tier-3 知识 vs RAG 召回闸门**——支持“知识 > RAG”论点的诚实 A/B 测试。 - **LLM 锚定的描述** — 一个可选的、需密钥验证的 `kb describe` 通道，让 LLM 为路由、实体、模块（按文件）和**包**（一个包级架构概览，综合了导入图 + 公共表面 + 成员模块摘要，并锚定在该包自身及其直接子模块的跨度上）编写自然语言摘要；每个声明都通过确定性的子属性闸门针对目标自身的跨度进行验证，因此未锚定的声明会被*丢弃*（这是反幻觉不变量，即使模型在循环中也是如此）。存储为 `extraction_method = "llm_grounded"`，锚定在代码跨度上。 - **增量重新索引** — `kb index --parent ` 从父快照复用未更改文件的跨度，并仅解析 diff；提取过程保持完整，因此结果与完全重新索引相同（由 HARD 闸门证明）。自动检测父节点；未索引时回退到完全索引。 - **11 个 HARD CI 评估闸门**（参见[开发](#development)）。 - **每夜 LLM 评判的 A/B 测试**（可选、需密钥验证、**非阻塞性**） — 一个回答 LLM 分别从 knowbase 的锚定上下文和基于源码的 RAG 上下文中回答每个问题，然后一个裁判 LLM 对**答案准确性**（对比手写标准答案）和**幻觉**进行打分。这是召回率之上的追踪指标；它永远不会阻塞 CI。 **尚未完成**（且刻意没有造假）：语义 / **LLM 锚定**提取层、从 git 历史中挖掘 ADR、锚定的业务流程提取、git push 时的增量重新索引，以及 Python 之外的语言。参见[路线图](#roadmap)。 ## 快速开始 ### 前置条件 - **Python 3.12+** - **uv** ([安装](https://docs.astral.sh/uv/getting-started/installation/)) - **PostgreSQL 17** — *运行 daemon* 所必需的。对于**测试套件**，你不需要运行中的服务器：它会通过 `initdb`/`pg_ctl` 启动一个**临时的本地 Postgres 集群**（无需 Docker）。你只需要机器上安装了 Postgres 的*二进制文件*（例如来自 Postgres.app 或系统包）。如果它们不在 `PATH` 中，请使用 `KB_PG_BINDIR` 指向它们；或者通过将 `KB_TEST_DB_URL` 设置为现有数据库来完全跳过临时集群。 ### 安装 ``` uv sync --extra dev # create the venv + install everything uv sync --extra dev --extra embed # add the embedding stack (CPU torch) for `kb embed` + semantic search ``` 基础的 `--extra dev` 安装不含 torch；`embed` 额外组件会拉取 sentence-transformers（通过指定的索引安装仅支持 CPU 的 torch），且仅为 `kb embed` 和 `search_knowledge` 所需。 ### 运行闸门 ``` uv run pytest src/kb/eval -q # the eleven HARD gates (spins an ephemeral local Postgres) ``` ### 索引一个 commit ``` uv run kb --help uv run kb index --sha --db-url # incremental: 从已索引的父节点复用未更改文件的 spans（仅解析 diff） uv run kb index --sha --parent --db-url ``` `--sha` 接受任何 commit-ish（sha、分支、tag 或默认的 `HEAD`）。数据库 URL 也可以来自 `KB_DB_URL` 环境变量，而不是 `--db-url`。运行时会打印其生成的內容： ``` indexed 4f1c2a9b8d3e (full): 12 files (12 parsed, 0 reused), 318 spans, 27 artifacts, 1 gaps gaps (unparseable, recorded): src/legacy/broken.py ``` **增量重新索引**（`--incremental`，或者隐含该操作的 `--parent `）会复用自父快照以来未更改文件的跨度，并仅解析已更改/新增的文件；extractor 仍然会完全运行，因此生成的快照与完全重新索引完全相同（由 HARD 闸门证明）。父节点会从 commit 的父节点中自动检测（第一个已索引的节点）；如果父节点缺失/未索引或第一方根目录发生更改，则会回退到完全索引。这使得 `kb index` 可以很方便地连接到 git 的 `post-receive` 钩子或 CI 步骤：`kb index --sha --parent `。 在底层，它针对那一个 commit 运行骨架流程 — `INGEST → STRUCTURE → EXTRACT → SNAPSHOT`。例如，在 `shop/orders.py` 第 1 行的一个类似 `from shop.billing import charge` 的 import 会变成一个 `import_edge` artifact（`import:shop.orders->shop.billing`），锚定在该 `file:line@sha` 处的确切 `import` 跨度上，且 `span_mapping: "exact"`。**“缺口”**指的是遇到语法错误的文件：它们会被*记录下来*，绝不静默丢弃，因此盲点是可见的，而非不可见的。 ### 添加语义搜索 ``` uv run kb embed --db-url # separate pass: populate artifact embeddings ``` `kb embed` 在最新快照的 artifact 上运行可替换的 embedding 提供者（默认是 sentence-transformers 的 `all-MiniLM-L6-v2`，可通过 `KB_EMBED_PROVIDER=openai` 选择 OpenAI），并将它们写入 `artifact.embedding`（pgvector）。它是幂等的，并且 torch 仅在此命令运行时加载——绝不会出现在索引路径中。 ### 生成语义描述（由 LLM 锚定） ``` uv run kb describe --db-url # separate, key-gated pass (ANTHROPIC_API_KEY / OPENAI_API_KEY) ``` `kb describe` 让 LLM（通过 `kb.llm`，`KB_LLM_PROVIDER` 取值为 {`anthropic`,`openai`}）为最新快照中的每个路由、实体、模块（按文件）和**包**（一个包级架构概览，锚定在该包自身及其直接子模块的跨度上，综合导入图 + 公共表面 + 成员模块摘要作为上下文）编写简短的自然语言摘要 + 结构化声明。**每个声明都会针对该目标自身的锚定跨度进行验证**——引用了代码中不存在的符号的声明会被丢弃，并且只有在有内容保留下来的情况下，`description` artifact 才会被存储，并锚定在这些代码跨度上（`extraction_method = "llm_g"`）。它需要 API 密钥，绝不会在 `kb index` 时运行，并且确定性的锚定闸门会在 CI 中无需密钥（使用桩 LLM）的情况下进行演练。 ### 服务于 AI agent (MCP) ``` uv run kb serve --db-url # read-only MCP server over stdio ``` 服务器暴露了三个只读工具，每个都返回带有来源信息的知识单元（提取方法 + 置信度 + 新鲜度）： | 工具 | 用途 | | --- | --- | | `find_provenance(file, line, sha?)` | 查询位于 `file:line@sha` 的锚定知识——该位置的跨度以及从中派生的 artifact。 | | `get_knowledge(target, sha?, token_budget?)` | 将逻辑键 / 文件 / 模块解析为其知识单元，进行排名并根据 token 预算进行裁剪（省略部分会被报告，绝不静默截断）。 | | `search_knowledge(query, sha?, k?, token_budget?)` | 对已嵌入的 artifact 进行余弦排名的语义搜索（需要 `kb embed`）。 | ### 交叉检查 API 契约（仅供评估） ``` uv run kb introspect app.main:app --repo # sandboxed app.openapi() oracle ``` `kb introspect` 在网络隔离的沙盒中运行 FastAPI 应用，并将其 `openapi()` 输出为 JSON——这是 Tier-1 API 闸门为**静态**契约 extractor 打分的 ground truth。它会执行用户代码，因此仅供评估，绝不会在索引期间运行。 ## 使用 Docker 运行 预构建镜像发布在 **GHCR**：`ghcr.io/v0ropaev/knowbase`（来自 `master` 的 `:edge` 标签，发布时的 `:X.Y.Z`/`:latest` 标签；支持 amd64+arm64 多架构）。默认镜像是 **slim** 版本（不含 torch — 支持 `index` / `migrate` / `serve` / `introspect`）；**`-embed`** 标签（例如 `:edge-embed`）添加了用于 `kb embed` 和语义搜索的 CPU 版 torch。 ``` docker pull ghcr.io/v0ropaev/knowbase:latest docker run --rm ghcr.io/v0ropaev/knowbase:latest --help ``` 作为 **MCP 服务器** (stdio)，指向你的 Postgres —— 这是 MCP 客户端启动的形式： ``` docker run -i --rm ghcr.io/v0ropaev/knowbase:latest serve --db-url ``` ### 使用 `docker compose` 进行本地开发/评估 捆绑的 compose 会启动一个 `pgvector` Postgres 以及基于此检出代码构建的 `kb` CLI： ``` docker compose up -d db # Postgres (pgvector) docker compose run --rm kb migrate # apply the schema docker compose run --rm kb index /workspace --sha HEAD # index the mounted repo docker compose run --rm -i kb serve # MCP over stdio ``` Compose 中的 Postgres 也从宿主机支持测试套件：`KB_TEST_DB_URL=postgresql+psycopg://postgres:postgres@localhost:5432/postgres uv run pytest src/kb/eval -q`。如果需要 embedding 支持，请使用 embed 额外组件构建镜像：`docker compose build --build-arg EXTRAS="--extra embed" kb`。 ## 架构 一个 Python 包 `kb`（uv，src 布局）。模块及其职责： | 模块 | 职责 | | --- | --- | | `kb.ids` | 内容寻址的标识哈希（**已锁定**）。`span_id` 排除了文件路径和字节偏移量；如果没有 ≥ 1 个锚定跨度，`artifact_id` 拒绝计算。 | | `kb.structural` | tree-sitter 跨度提取；结构指纹是一个标准化的 S-表达式（仅限命名节点；剔除注释和 docstring；保留标识符/字面量）。位置按 SHA 记录。 | | `kb.store` | 通过 Alembic 管理的单一 PostgreSQL；内容寻址的幂等写入；≥ 1 个 `derived_from` 的不变量在应用内以及由延迟约束触发器强制执行。 | | `kb.git` | pygit2 摄取——在特定的 SHA 处读取 blob（无需 checkout）——以及基于 diff 的失效种子。 | | `kb.extract.deterministic.imports` | 确定性的 import / 依赖边：由行锚定的 tree-sitter 跨度，grimp 边解析。 | | `kb.extract.deterministic.fastapi_contract` | 静态 FastAPI API 契约 extractor；跨文件锚定路由（handler + `response_model` 类），绝不导入用户代码。 | | `kb.extract.deterministic.entities` | 静态领域实体 extractor——pydantic / dataclass / SQLAlchemy 类及其字段，锚定在类定义上**并且跨文件锚定到它们引用的实体**（字段类型 + `relationship()`）；检测信号和限制记录在 payload 中。 | | `kb.extract.deterministic.library_surface` | 静态库公共 API 表面 extractor——包从其 `__init__.py` 导出的每个名称对应一个 `public_symbol`（以 `__all__` 为准），`__init__` 重导出**跨文件**解析为定义它的函数/类；已通过独立的 griffe 静态 ground truth 验证。绝不导入用户代码。 | | `kb.introspect` | 沙盒化、网络隔离的 `app.openapi()` ground truth——仅供 API 闸门评估，绝不在索引路径上。 | | `kb.mcp` | 只读 MCP 服务器及其携带来源信息的记录：`find_provenance`、`get_knowledge`、`search_knowledge`。 | | `kb.embed` | 可替换的 embedding 适配器（默认为 sentence-transformers，可选 OpenAI）+ 快照填充。torch 被隔离在 embed 额外组件和懒加载之后。 | | `kb.rag` | 冻结的 pgvector 基于源码的 RAG 基准——知识 vs RAG A/B 测试的“另一臂”（无来源信息，无锚定）。 | | `kb.extract.semantic` | LLM 锚定的提取（`kb describe`）：路由/实体/模块**以及每个包的架构概览**的自然语言描述（从导入图 + 公共表面 + 成员摘要中进行丰富的综合，锚定在代码跨度上），带有确定性的子属性闸门（`grounding.validate_claims`），会丢弃任何不被目标跨度支持的声明。独立的需密钥验证通道；绝不在 `index` 上运行。 | | `kb.daemon.cli` | `kb` CLI：`index`（完全或 `--incremental`/`--parent`）、`migrate`、`embed`、`describe`、`serve` (MCP) 和 `introspect`——全部可用。 | | `kb.eval` | 11 个 HARD CI 闸门（标识重现性、对抗性锚定、Tier-1 import ground truth、Tier-1 API ground truth、Tier-1 实体 ground truth、Tier-1 库表面 ground truth、Tier-3 知识 vs RAG 召回率、Tier-4 一跳失效、不变量、语义锚地下限、增量重新索引等价性）以及辅助的 MCP / embed / store 套件。 | 核心表：`commit_ref`、`branch_ref`、`code_span`、`span_occurrence`、`artifact`（现在包含 `embedding vector(384)` + `embedding_model_id`）、`artifact_derived_from`、`snapshot_entry` 和 `rag_chunk`（基准臂）。 ## 开发 ``` uv sync --extra dev # venv + install uv run ruff check src/kb # lint uv run mypy # strict type-check uv run pytest src/kb/eval -q # the eleven HARD eval gates ``` CI（GitHub Actions，工作流 **"CI"**，`.github/workflows/ci.yml`）运行 ruff、`mypy --strict` 以及针对 `pgvector/pgvector:pg17` 服务的评估闸门（并缓存了 embedding 模型）。阻塞合并的**11 个 HARD 闸门**： 1. **标识重现性** — 格式化/注释/docstring/位置的改变绝不能改变 `span_id`；而重命名则必须改变。纯标识核心，无数据库。 2. **对抗性锚定** — 未锚定的 artifact 被*两层*拒绝（应用的 `GroundingError` 和数据库的延迟 `artifact_grounded_check` 触发器）；真正锚定的 artifact 则能顺利提交。 3. **Tier-1 import ground truth** — 提取的 import 边与手工标记的 ground truth 匹配，并锚定在实际的 import 语句跨度上；动态 import 被断言为一个*已知*缺口，而不是静默丢失。 4. **Tier-1 API ground truth** — 静态提取的 FastAPI 契约等于应用自身的 `openapi()`（来自沙盒化的 introspect ground truth），并且断言了路由的跨文件锚定（handler + `response_model`）。 5. **Tier-1 实体 ground truth** — 提取的 pydantic / dataclass / SQLAlchemy 实体及其字段与手工标记的 ground truth 匹配，每个都锚定在其类跨度上；一个纯粹声明性的 `Base` 被正确识别为*不是*实体，而 `create_model(...)` 模型被断言为一个*已知*缺口。 6. **Tier-1 库表面 ground truth** — 静态提取的包公共 API 表面（以 `__all__` 为准，`__init__` 重导出**跨文件**解析）等同于独立的 **griffe** 静态 ground truth；下划线私有名称被排除，而第三方/动态 `__all__` 重导出虽被锚定但被标记，并被断言为一个*已知*缺口。 7. **Tier-3 知识 vs RAG 召回率** — knowbase 对每一个跨文件问题的跨文件召回率 recall@k == 1.0（API 契约**和**领域实体：在每种情况下，一个 artifact 已经跨越了两个文件，因此下限是*结构性的*，与 embedding 质量无关）；RAG 臂会被报告但**绝不进行断言**，因此模型升级不会使 CI 变红。 8. **Tier-4 一跳失效** — 内容 diff 恰好使那些锚定跨度发生改变的 artifact 失效（集合相等：没有过度失效，也没有陈旧的幸存者）；版本升级则会使一切失效。 9. **不变量** — 零孤儿（每个快照 artifact 都被锚定），并且重新索引同一个 SHA 会产生完全相同的 artifact id 集合。 10. **语义锚地下限** — LLM 锚定描述器的声明通过确定性的子属性闸门针对 artifact 自身的跨度进行验证；对抗性的伪造声明会被*丢弃*，绝不会存储（在桩 LLM 上运行，因此无需 API 密钥即可作为闸门）。 11. **增量重新索引等价性** — 增量重新索引（从父节点复用未更改文件的跨度，仅解析 diff）产生与相同代码树的完全重新索引*完全相同*的 `{logical_key: artifact_id}` 快照，并且对于未更改的文件，解析被证明是跳过的（反向断言）；缺失/未索引的父节点则回退到完全索引。 `kb.ids`（以及 `kb.structural`）中的标识规则是**锁定的**：更改其中一个属于破坏性变更，需通过提升 `NORMALIZATION_VERSION` / `extractor_version` 来管控，以确保现有的摘要被失效，而不是发生静默冲突。 ## 路线图 诚实的终极目标是证明，在真实问题上，锚定的**知识层胜过基于代码的 RAG**。之所以能做到这一点，原因在于其结构性：为了回答一个跨文件的契约问题，RAG 必须在文件之间独立检索*两个*源码块，而一个锚定的 knowbase artifact 已经跨越了两者——这正是 Tier-3 闸门所衡量的。 ``` %%{init: {'theme':'base','themeVariables':{'background':'#FAF3E7','primaryColor':'#FAF3E7','primaryTextColor':'#071812','primaryBorderColor':'#1C4434','lineColor':'#3C5B4E','secondaryColor':'#EDE3D2','tertiaryColor':'#F3EAD9','textColor':'#1C4434','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart LR Q["Q: shape of GET /api/orders response?"] Q --> A["api:GET /api/orders
(one grounded artifact)"] Q --> RAG A --> H["routes.py — handler span ✓"] A --> M["schemas.py — response_model span ✓"] subgraph RAG["RAG-over-source — independent top-k chunks"] direction TB C1["chunk · routes.py ✓"] C2["chunk · schemas.py — only if retrieved"] C3["chunk · other.py ✗"] end ``` 下一个里程碑： - [x] **每夜 LLM 评判的 A/B 测试**（需密钥验证，非阻塞性） — 召回率之上的锚定答案准确率 + 幻觉率。*(已发布)* - [ ] **LLM 锚定的语义层** — 仍携带 ≥ 1 个跨度的基于模型的 artifact（`extraction_method = "llm_grounded"`）。 - [~] **git push 时的增量重新索引** — *核心功能已发布*：`kb index --incremental`/`--parent` 从父快照复用未更改文件的跨度（提取过程保持完整；等价性已设为闸门）。实时的监控/推送 daemon 是剩余的部分。 - [ ] 从 git / PR 历史中**挖掘 ADR**。 - [ ] **锚定的业务流程提取。** - [ ] Python 之外的**更多语言**。 ## 安全 请负责任地报告漏洞——参见 [SECURITY.md](./SECURITY.md)。请勿为了报告安全问题而开启公开的 issue。 ## 许可证 [AGPL-3.0-or-later](./LICENSE)。

标签：DevOps工具, MCP, Python, 人工智能, 代码库分析, 无后门, 测试用例, 溯源, 用户模式Hook绕过, 请求拦截, 逆向工具