agentforge-graph

<!-- NOTE: 为 agentforge-graph（从 scaffold README 分支）定制 --> # agentforge-graph [](https://github.com/Scaffoldic/agentforge-graph/actions/workflows/ci.yml) [](https://pypi.org/project/agentforge-graph/) [](https://pypi.org/project/agentforge-graph/) [](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE) > **将任何代码仓库或整个组织转化为知识图谱，您的编码代理可以实际推理。** 符号、调用、导入、**API 路由**、**ORM 模型**、依赖注入、架构决策、git 历史记录、LLM 摘要 — 一个键入的、带有溯源的图谱，通过 **MCP** 以单个命令提供。扩展它从一个仓库到 **联合工作区**，具有 **跨服务跟踪**，在一个 **中心**索引中托管给团队。 普通代码图工具回答 *"什么连接着。"* 代理还需要 *"这是什么**，什么决策控制它，什么是 API 接口，哪些表触及它，谁调用它，发生了什么变化。* **agentforge-graph 将解析结构、框架语义、架构决策、git 演变和 LLM 丰富度放入一个图谱中，代理可以遍历 — 每个事实都带有其溯源。** 建立在 [AgentForge](https://pypi.org/project/agentforge-py/) 之上。 ```bash pip install agentforge-graph # ← 引擎在盒子里；无需运行其他程序 ckg index . # 仓库 → 键入图谱（秒）（无需凭证，无需服务器） ckg serve-mcp --repo . # → 10 个只读工具给您的代理 ``` <p align="center"> <img src="https://raw.githubusercontent.com/Scaffoldic/agentforge-graph/main/docs/assets/demo.gif" alt="ckg 索引一个 FastAPI + SQLAlchemy 应用，并显示其路由、ORM 模型和依赖注入图" width="820"> <br> <em>索引一个 FastAPI + SQLAlchemy 应用 → 其路由、ORM 模型（带关系）和 DI 图 — 无需凭证，无需服务器。</em> </p> --- ## 您从盒子里得到什么 - 🧩 **一个键入的代码图，命令即可** — `pip install` → `ckg index .` → 文件、类、函数、方法，带有稳定的基于描述符的 ID 和 `CONTAINS`/`IMPORTS`/`CALLS`/`INHERITS` 边。**嵌入 Kuzu + LanceDB 在 `.ckg/` 下 — 无需服务器，无需云，无需配置。** 10 种语言：Python、TypeScript、JavaScript、Go、Ruby、PHP、Java、C#、C++、Rust。 - 🌐 **框架语义作为图边** *(差异化因素)* — 路由、ORM 模型和 DI，而不仅仅是调用。`ckg routes` 是您的 API 接口，`ckg models` 是您的数据模型，`ckg services` 是您的注入映射 — 跨越 **11 个软件包**：FastAPI、Flask、SQLAlchemy、Django（Python）；Express、NestJS（JS/TS）；Spring（Java）；Gin（Go）；ASP.NET（C#）；Laravel（PHP）；Rails（Ruby）。 - 🏛️ **决策 ↔ 代码** *(差异化因素)* — 吸收 ADRs/docs 并将它们链接到它们所**管辖**的代码。一个命中 `payments/` 表面 *"ADR-0012（已接受）：幂等密钥必须是客户端侧"* **在** 代理编辑之前。 - 🕰️ **内置 Git 演变** — `ckg history <symbol>`、`ckg changed-since <ref>` 和 `--as-of <commit>` 重建。变更率和作者身份随图谱变化。 - 🔎 **混合检索** — 矢量搜索 **entry** → 键入 **图扩展**。用自然语言提问，获取 *连接* 的上下文：符号、调用者以及管辖决策。 - ⚡ **默认增量** — 仅重新索引差异。编辑 5k 文件仓库中的 3 个文件 → 数秒，而不是分钟。嵌入/丰富度仅重新计算更改的内容。 - 🤖 **代理原生** — 通过 **MCP（10 个工具）** 或作为原生 AgentForge 工具集提供。每个响应都带有过时信封。 - 🧠 **LLM 丰富度，预算和可选** — 设计模式标签（*"此类别是存储库，"*，带有置信度和理由）和自下而上的模块摘要，所有 `llm` 溯源。**CI 无需模型调用或云凭证。** - 🏢 **从一个仓库扩展到整个组织** — 将索引 **集中** 托管（共享目录或 SurrealDB/Neo4j），一次构建，一次由多个只读消费；提供一个多仓库 **工作区**，来自一个联合 MCP 端点；并 **跟踪跨服务请求** — `ckg services-map` / `ckg trace` 绘制跨服务调用图（HTTP 客户端 → 路由，通过路径或 OpenAPI 合同匹配）。 **状态：0.6.2 — 组织规模化，通过一个命令构建，现在通过一个命令连接。** 0.5 添加了集中式托管、联合多仓库工作区和跨服务跟踪；0.6 添加了 **构建端** — 从一个 `workspace.yaml` + 一个配置 + `ckg build --workspace`（成员本地或通过 git URL），带有快速失败的 `ckg doctor` 验证和配置/CLI 控制的跟踪。0.6.2 添加了 **`ckg setup`** — 一个命令将图谱连接到您的代理。 在 [PyPI](https://pypi.org/project/agentforge-graph/) 上发布。每个语言包都在一个真实的 OSS 仓库中通过凭证启用的嵌入/检索/丰富运行进行验证；一个真实的代理在无需关注的情况下回答工具问题。请参阅 [`CHANGELOG`](https://github.com/Scaffoldic/agentforge-graph/blob/main/CHANGELOG.md) 和 [`docs/features/TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/features/TRACKER.md)。 --- ## 以三种方式运行它 — 一个仓库，一个工作区或一个中央存储 ```bash # 1) 单个仓库 — 秒级键入图谱 ckg index . && ckg routes . # 2) 中央存储 — 在仓库外托管索引，只读 # （在 ckg.yaml 中设置 store.central_root；由 CI 构建，一次读取多次） ckg status . --read-only # 3) 工作区 — 使用一个命令构建多个仓库，然后是跨服务图 ckg build --workspace workspace.yaml # 索引（+嵌入）每个成员，一个命令 ckg services-map --workspace workspace.yaml # 谁调用谁（HTTP → 路由） ckg trace payments --workspace workspace.yaml --direction upstream # 辐射范围 ``` > **配置一次，快速失败。** `workspace.yaml` 中的 `defaults:` 块（存储位置、嵌入器、只读）由每个成员继承，并具有成员特定的覆盖；成员可以是 **本地路径或 git URL**。`ckg doctor [--workspace]` 在构建前验证配置（安装的驱动程序、存在的凭证）。 <p align="center"> <img src="https://raw.githubusercontent.com/Scaffoldic/agentforge-graph/main/docs/assets/setups.gif" alt="ckg 运行三种方式：单个仓库（索引 + 路由），中央存储（托管 + 只读）和工作区（跨服务调用图 + 跟踪）" width="820"> <br> <em>单个仓库 → 中央存储 → 工作区 — 跨服务调用图和辐射范围，全无凭证。</em> </p> → 选择您的路径： **[单个仓库](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** · **[工作区](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** · **[中央存储](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)**. --- ## 快速开始 > **更喜欢引导式演练？** 选择您的设置 — **[单个仓库](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)**（~10 分钟）， **[工作区](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** （微服务，一个联合端点），或 **[中央存储](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)** （组织级共享索引） — 来自 **[入门中心](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)**。或者浏览所有 [逐步指南](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md)。 ```bash pip install agentforge-graph # 引擎已包含（tree-sitter + kuzu + lancedb） # 1) 将仓库索引到图谱中 — 每次运行都是增量的 ckg index . # 文件/类/函数/调用（+ ADRs，路由，模型...） # 探索图谱 — 无嵌入，无凭证，无服务器 ckg map --budget 2000 # 中心性排名的仓库定位 ckg routes # API 接口：METHOD PATH → 处理程序 ckg models # ORM 数据模型：表，字段，关系 ckg services # 依赖注入映射 ckg decisions --status accepted # ADRs 和它们管辖的内容 ckg history <symbol-id> # 何时/谁/变更记录 ckg status # 索引提交，过时，节点计数 ``` 添加 **语义搜索** 与任意嵌入提供商（AWS Bedrock、OpenAI 或本地 OpenAI 兼容服务器 — 请参阅 [模型](#models--pick-a-provider-or-bring-your-own)）： ```bash pip install "agentforge-graph[bedrock]" # 或 [openai] ckg embed . # AST 块 → 矢量 ckg query "如何验证身份令牌" # 排名，*连接* 上下文 ckg query --symbol "<id>" --mode impact # 反向依赖 — “谁调用这个” # 可选：显式，预算 LLM 丰富度 ckg enrich . --all --budget-usd 2 # 设计模式标签 + 模块摘要 ckg tagged Repository # 符号标记为设计模式 ``` ### 看看它在行动 ```text $ ckg index . indexed 1c2f3a4 · 412 files · 5,290 nodes / 9,133 edges · 3.1s $ ckg routes POST /payments/{pid}/refund → refund() （app/api.py:42） GET /health → health() （app/api.py:16） $ ckg models users [users] （app/models.py:7） 字段：id, name, email 关系：posts→posts （关系） $ ckg query "如何验证身份令牌" auth/tokens.py:88 TokenValidator.validate （余弦 0.71） ← 由 api/middleware.py:23 调用 require_auth ⚖ 由 ADR-0007（已接受）：签名密钥必须每 90 天轮换一次 ``` 最后一个块是重点：自然语言问题返回符号，**谁调用它**，以及**管辖决策** — 连接，具有溯源。 ### 为代理提供服务 通过 MCP 只读 — **10 个工具**：`ckg_repo_map`、`ckg_search`、`ckg_symbol`、`ckg_impact`、`ckg_neighbors`、`ckg_status`、`ckg_routes`、`ckg_decisions`、`ckg_explain`、`ckg_history`： ```bash ckg setup # 为您配置代理（写入 .mcp.json） claude mcp add ckg -- ckg serve-mcp --repo . # 或手动执行 — stdio（子进程） ckg serve-mcp --repo . --transport http # 或 HTTP → http://127.0.0.1:8765/mcp ``` `ckg setup` 自动编写代理的 MCP 配置（一个可提交的仓库 `.mcp.json`），显示差异并可逆转 `--undo` — 请参阅 [指南 11](docs/guides/11-agent-auto-configuration.md)。通过 HTTP，指向任意 MCP 客户端到 URL：`{"mcpServers": {"ckg": {"url": "http://127.0.0.1:8765/mcp"}}}`。 或作为原生 AgentForge 工具集： ```python from agentforge import Agent from agentforge_graph.serve import code_graph_tools agent = Agent(model="anthropic:claude-sonnet-4-6", tools=code_graph_tools(".")) ``` → 完整指南（工具模式、客户端配置、防护措施、过时信封）： [`docs/guides/10-using-over-mcp.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md). --- ## 图谱中有什么 | 能力 | 您得到什么 | |---|---| | **键入代码图** | 文件、类、函数、方法，具有稳定的基于描述符的 ID；`CONTAINS`/`IMPORTS`/`CALLS`/`INHERITS` 边。保守，无猜测的解析，跨越 10 个语言包。 | | **框架感知** *(差异化因素)* | `Route → HANDLED_BY → 处理程序`，`DataModel → HAS_FIELD`/`RELATES_TO`，`Service → INJECTED_INTO` — 跨越 11 个软件包：FastAPI、Flask、SQLAlchemy、Django、Express、NestJS、Spring、Gin、ASP.NET、Laravel、Rails。`ckg routes`/`models`/`services`。 | | **决策 ↔ 代码** *(差异化因素)* | ADRs/docs 被吸收并链接到它们所**管辖**的代码；文档散文嵌入 + 可搜索。 | | **时间/ git 演变** | 每个符号的历史记录、变更率、作者身份；`changed-since`、`as-of` 重建。 | | **混合检索** | 矢量入口 → 键入 **图扩展**。连接上下文，而不是扁平列表。 | | **LLM 丰富度** *(差异化因素)* | 预算的设计模式标签 + 自下而上的模块摘要 — `llm` 溯源，可选择退出。 | | **代理原生** | 只读 MCP（10 个工具）或原生 AgentForge 工具集；每个响应都带有过时信封。 | | **嵌入式** | 本地 Kuzu 图谱 + LanceDB 矢量存储 `.ckg/`。服务器端存储和模型可插拔。 | --- ## 检索质量（衡量） 检索是代理端面对的主要接口，因此我们衡量它 — 而不是印象。在一个 **客观** 的自然语言→代码基准（每个文档符号的文档字符串是查询，该符号是正确答案；标签直接来自图谱的 `DESCRIBES` 边，验证无泄漏），超过 **388 个查询，涵盖 4 个真实的 OSS 仓库**（click、httpx、flask、fastapi）使用 Bedrock `cohere.embed-v4`： | | 基础混合检索 | + Bedrock 交叉编码器重排名（w=0.3） | |---|---|---| | **MRR** | 0.952 | 0.971 | | **recall@1** | 0.915 | 0.948 | 基准测试的基础检索几乎总是将正确的代码放在 **排名 ≈ 1**。可选的交叉编码器重排器（Bedrock Rerank — 无需 torch）为 **~440 ms/query** 添加了小但 **统计学上显著** 的精度增益（ΔMRR +0.019，95% CI [+0.008，+0.031]，p < 0.001）。因此它是 **可选** 的，当 top-1 精确度值得额外的延迟时。 --- ## 存储 — 使用什么数据库，可以更换吗？ **默认情况下，无需运行任何操作。** 图谱存储在嵌入式 **Kuzu** 数据库中，向量存储在嵌入式 **LanceDB** 索引中，均位于仓库下的 `.ckg/` 目录（ADR-0006）。无需配置，无需服务器。 存储 **可插拔**，有两个接口 — `GraphStore` 和 `VectorStore`（[`core/contracts.py`](https://github.com/Scaffoldic/agentforge-graph/blob/main/src/agentforge_graph/core/contracts.py)）— 由 **驱动程序注册表** 使用入口点组（[`store/registry.py`](https://github.com/Scaffoldic/agentforge-graph/blob/main/src/agentforge_graph/store/registry.py)）解析： ```yaml # agentforge.yaml （引擎配置位于 app: 下） app: store: graph: { driver: kuzu } # 内置 vectors: { driver: lancedb } # 内置 ``` 三种服务器后端作为可选项提供：**Neo4j**（图谱），**Postgres/pgvector**（向量）和 **SurrealDB** — 多模型，因此一个服务器既是图谱又是向量存储。每个后端都通过相同的 `GraphStoreConformance` / `VectorStoreConformance` 套件，该套件在 CI 中与实时服务器一起运行。任何其他（SurrealDB 除外）都是一个 **独立适配器**：实现接口，通过一致性套件，注册一个入口点 — 然后它就是 `pip install + 一行配置`，无需核心更改。 → [`docs/guides/09-storage-backends.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md)。 ## 模型 — 选择提供商或自带 每个模型边界都是一个 **接口**，由提供商注册表解析，因此切换提供商是一行配置更改（在 `agentforge.yaml` 中的 `app:` 下）— 而不是代码更改： | 接口 | 随附第一方 | 选择 | |---|----|----| | `Embedder` | `bedrock` (Cohere `embed-v4`) · `openai` (包括 **本地** OpenAI 兼容) · `fake` (CI) | `embed.driver` | | `PatternJudge` / `Summarizer` | `bedrock` · `anthropic` (直接 API) · `scripted` (CI) | `enrich.provider` | - **在 AWS 上？** 默认的 `bedrock` (Claude + Cohere) 使用您的 AWS 凭证。 - **不在 AWS 上？** `enrich.provider: anthropic` （设置 `ANTHROPIC_API_KEY`）+ `embed.driver: openai` （设置 `OPENAI_API_KEY`）提供一个完整的实时路径，无需 AWS。 - **本地/自托管？** 将 `embed.base_url` 指向任何 OpenAI 兼容的服务器（Ollama，vLLM，LM Studio）— 相同的 `openai` 驱动程序。 - **完全离线？** `embed.driver: fake` + `enrich.provider: scripted`。 CI 使用确定性伪造品，因此 **无需模型调用或云凭证即可构建或测试**。 → [`docs/guides/08-model-providers.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md). --- ## 架构 参见 **[`docs/ARCHITECTURE.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/ARCHITECTURE.md)** 获取完整概述（层级图、数据模型、每个管道的 ASCII 字符表示、扩展点）。简而言之：一个 `core` 包含接口 + 值类型，一个 **确定性引擎** 从不导入框架（解析、存储、解析、嵌入、检索、**框架**、知识），以及一个薄 **框架层**（`serve` = MCP/Tools，`enrich` = 预算控制的 LLM）。 ``` ckg CLI / MCP 服务器 / Agent │ serve · enrich （框架层 — 可能导入 agentforge） │ ingest · store · 切片 · 嵌入 · 检索 · 图谱映射 · 框架 · 知识 · 时间 │ （确定性引擎 — 无 agentforge） core: 接口 · 模型 · SymbolID · 溯源 · 类型 │ Kuzu（图谱）+ LanceDB（向量） 在 .ckg/ 下 ``` --- ## 配置与安装额外功能 一份配置文件：**`agentforge.yaml`**。 - **框架密钥** 在顶层（智能体模型、预算、MCP）— 严格。 - **引擎配置** 在框架的 **`app:`** 直通下：`store`、`ingest`、`chunking`、`embed`、`retrieve`、`repomap`、`serve`、`frameworks`、`knowledge`、`enrich`、`temporal`。引擎使用纯 pyyaml 读取 `app:`，从不导入框架（ADR-0001），并且是宽容的（未知键被忽略）。 - 一个独立的 **`ckg.yaml`**（顶层相同的块）仍然支持无框架使用；引擎自动发现任一文件。 基础 `pip install agentforge-graph` 包括确定性引擎（tree-sitter、kuzu、lancedb、networkx）。可选的额外功能添加提供商/后端： | 安装 | 添加 | |---|---| | `pip install agentforge-graph` | 基础：引擎 + 框架运行时 + MCP 服务 | | `…[bedrock]` | `boto3` — Bedrock 嵌入 + Claude 丰富 | | `…[openai]` | `openai` — OpenAI / 本地 OpenAI 兼容嵌入 | | `…[neo4j]` / `…[pgvector]` | 可选服务器图 / 矢量后端 | | `…[surrealdb]` | 可选单服务器 — 图 **和** 矢量（多模型） | | `…[rerank]` | 句子转换器交叉编码器（默认关闭） | Anthropic-API 丰富路径（`enrich.provider: anthropic`）不需要额外 — `anthropic` SDK 随基础安装附带。 ## 贡献与 AI 辅助开发 此仓库旨在与 AI 智能体一起使用。从这里开始： - **[`CONTRIBUTING.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/CONTRIBUTING.md)** — 设置、质量门、每个功能的开发流程和逐步操作指南（添加语言包、框架包、存储后端、模型适配器、MCP 工具、丰富器）。 - **[`AGENTS.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/AGENTS.md)** — 由 Claude Code 和其他 AGENTS.md 感知助手读取。（ [AGENTS.md 惯例](https://agents.md)）；AI 助手必须尊重的不变性。 - **[`docs/ARCHITECTURE.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/ARCHITECTURE.md)** — 系统地图。 ## 文档地图 | 文档 | 内容 | |---|---| | [`docs/ARCHITECTURE.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/ARCHITECTURE.md) | 高级架构 + 每个流程（ASCII） | | [**`docs/guides/`**](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md) | **逐步指南**（每个都有 TL;DR）。**入门 — 选择您的设置：** [单个仓库](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md) · [工作空间](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md) · [中央存储](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)。**主题指南：** [02 索引和检索](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/02-indexing-and-retrieval.md) · [03 框架提取](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/03-framework-extraction.md) · [04 跨文件解析](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/04-cross-file-framework-resolution.md) · [05 架构决策](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/05-architecture-decisions.md) · [06 时间/历史](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/06-temporal-history.md) · [07 丰富](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/07-enrichment.md) · [08 模型提供商](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md) · [09 存储后端](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md) · [10 通过 MCP 使用](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md) | | [`examples/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/examples) | 可运行的示例仓库（索引 → 路由/模型/服务/查询） | | [`docs/adr/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/adr/) | 9 个架构决策记录（*原因*） | | [`docs/features/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/features/) + [`TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/features/TRACKER.md) | 12 个功能规格 + 状态板 | | [`docs/design/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/design/) | 每个功能的设计文档（*如何*，预构建） | ## 许可证 [**Apache-2.0**](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE) — 允许的，具有明确的专利授予和专利反击条款。参见 [`LICENSE`](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE) 和 [`NOTICE`](https://github.com/Scaffoldic/agentforge-graph/blob/main/NOTICE)。与 AgentForge 对齐，后者也是 Apache-2.0。