esolnguyen/ai-knowledge-graph

# AI 知识图谱 ## 目录 - [工作原理](#how-it-works) - [安装说明](#installation) - [快速入门](#quickstart) - [使用方法](#usage) - [构建图谱](#build-a-graph) - [探索图谱](#explore-the-graph) - [保持图谱最新](#keep-the-graph-fresh) - [同步 Azure DevOps](#sync-azure-devops) - [AI 助手集成](#ai-assistant-integration) - [命令参考](#command-reference) - [开发](#development) ## 工作原理 该 pipeline 分四个阶段运行： 1. **检测**：遍历目标目录并识别每个受支持的源文件。 2. **提取**：使用 tree-sitter 解析每个文件，为类/函数/模块生成节点，为调用/导入生成边。 3. **构建**：组装 NetworkX 图谱，运行 Louvain 社区检测，评估内聚性，并标记 god 节点以及令人惊讶的跨社区边。 4. **导出**：将 `graph.json` (GraphRAG payload) 和 `REPORT.md` (审计报告) 写入 `/aikgraph-out/` 下。 仅基于 AST 的 `update` 命令涵盖此流程。若需**语义层**（跨文件概念边、docs/README 理解、图像/PDF 提取、依据边），请从 AI 编码助手中运行完整的 `/aikgraph` 流程（参见 [AI 助手集成](#ai-assistant-integration)）。 ## 安装说明 在仓库根目录下执行： ``` cd ~/source/aikgraph pip install -e . --no-deps ``` 验证 CLI 是否在你的 `PATH` 中： ``` aikgraph --help ``` 你应该会看到 `Usage: aikgraph ` 及其随后的命令列表。 ## 快速入门 端到端：在一个或多个仓库上构建图谱，接入 Kiro，并让 Kiro 读取该图谱。 ### 1. 将你想要图谱化的代码收集到一个文件夹中 选择一个工作区文件夹（磁盘上的任何位置）。将你想要加入图谱的每个仓库克隆到其下： ``` mkdir -p ~/projects/my-workspace cd ~/projects/my-workspace git clone git@github.com:your-org/service-a.git git clone git@github.com:your-org/service-b.git git clone git@github.com:your-org/shared-lib.git ``` 该图谱将工作区视为一个整体——跨仓库的调用和导入会变成真实的边。 ### 2. 在该文件夹内构建图谱 ``` cd ~/projects/my-workspace aikgraph update . ``` 输出会保存在**工作区内部**，而不是你的主目录中： ``` ~/projects/my-workspace/ ├── service-a/ ├── service-b/ ├── shared-lib/ └── aikgraph-out/ <-- created by `aikgraph update` ├── graph.json ├── REPORT.md ├── graph.html (open in browser) ├── graph.svg └── obsidian/ (open as an Obsidian vault) ``` ### 3. 安装 Kiro 技能 ``` cd ~/projects/my-workspace aikgraph kiro install ``` 这会做两件事： - 将技能放置在 `~/.kiro/skills/aikgraph/SKILL.md` —— 这是**全局的**，因此 Kiro 会在每个项目中都加载它。 - 写入 `./.kiro/steering/aikgraph.md` 并准备 `./.kiro/aikgraph-out/` —— 这是**项目局部的**。之后，`aikgraph update` 会将图谱写入 `./.kiro/aikgraph-out/` 而不是 `./aikgraph-out/`（标记文件会重定向输出路径）。 重新运行 update 以便将输出保存在支持 Kiro 的位置： ``` aikgraph update . ls .kiro/aikgraph-out/ # graph.json, REPORT.md, graph.html, ... ``` ### 4. 打开 Kiro 并询问有关代码的问题 在 Kiro 中打开工作区。常驻的 steering 文件会告诉 Kiro 在回答架构问题之前先读取 `./.kiro/aikgraph-out/REPORT.md`，而该技能会教会它运行 `aikgraph query`、`aikgraph path` 和 `aikgraph explain` 来进行定向查找。你可以这样提问： - “向我讲解 service-a 是如何调用 shared-lib 的。” - “这个工作区中的 god 节点有哪些？” - “从 `LoginForm` 到 `UserRepository` 的最短路径。” 当代码发生更改时，重新运行 `aikgraph update .`（或者设置 `aikgraph watch .` / `aikgraph hook install` —— 参见 [保持图谱最新](#keep-the-graph-fresh))。 ## 使用方法 示例以 `~/projects/my-project` 为目标（任何源文件夹均可）。请替换为你自己的路径。 ### 构建图谱 ``` aikgraph update ~/projects/my-project # JSON + REPORT only (default) aikgraph update ~/projects/my-project --html --svg --obsidian # generate all extra outputs aikgraph update ~/projects/my-project --html # add interactive HTML only ``` 输出保存在 `/aikgraph-out/`： | 文件 / 文件夹 | 用途 | 启用方式 | |---------------|---------|--------| | `graph.json` | 完整的图谱 payload（兼容 GraphRAG） | 始终 | | `REPORT.md` | 涵盖 god 节点、社区和后续问题的审计报告 | 始终 | | `graph.html` | 交互式 vis.js 可视化（暗色主题、搜索、社区图例） | `--html` | | `graph.svg` | 静态 matplotlib 渲染（需要 `matplotlib`） | `--svg` | | `obsidian/` | Obsidian 知识库：每个节点一个带有 wikilink 的 `.md` 笔记、社区概览笔记、`graph.canvas`，以及 `.obsidian/graph.json` 中按社区划分的颜色 | `--obsidian` | 预期的最后一行： ``` [aikgraph watch] Rebuilt: N nodes, M edges, K communities ``` ### 探索图谱 导出一次 `GRAPH`，然后进行查询： ``` GRAPH=~/projects/my-project/aikgraph-out/graph.json aikgraph explain "AuthModule" --graph $GRAPH aikgraph path "LoginForm" "UserRepository" --graph $GRAPH aikgraph query "how does extraction talk to core" --graph $GRAPH aikgraph query "auth flow" --dfs --budget 3000 --graph $GRAPH ``` 或者 `cd` 进入目标文件夹并省略 `--graph`。它默认指向 `./aikgraph-out/graph.json`。 | 命令 | 用途 | |---------|---------| | `aikgraph explain ""` | 对某个节点及其相邻节点的通俗语言描述 | | `aikgraph path "" ""` | 两个概念之间的最短路径 | | `aikgraph query ""` | 用于获取广泛上下文的 BFS 遍历（添加 `--dfs` 以追踪链条） | | `aikgraph query "" --budget N` | 将回答限制在 N 个 token（默认 2000） | ### 保持图谱最新 选择适合你工作流的方式： | 方式 | 命令 | 何时使用 | |----------|---------|-------------| | **手动** | `aikgraph update ` | 在进行重大编辑后的一次性重建 | | **Git hook** | `aikgraph hook install` (在目标仓库中) | 每次提交 / 检出时自动重建 | | **文件监视器** | `aikgraph watch ` (需要 `watchdog`) | 保存时实时重建，3 秒防抖 | 使用 `aikgraph hook status` 和 `aikgraph hook uninstall` 来管理钩子。监视器在前台运行；使用 `Ctrl+C` 停止。 ### 同步 Azure DevOps 将 Azure DevOps 项目的工作项和仓库拉取到与你的代码相同的图谱中。工作项（PBIs、bugs、epics）将成为文档节点；仓库也成为文档节点，其默认分支的检出将反馈给 AST 提取器，因此工单与真实代码符号之间的交叉链接会显示为边。 设置一次凭证，然后将 `--project` 传递给 `aikgraph update`： ``` export AZURE_DEVOPS_ORG="your-org" export AZURE_DEVOPS_PAT="..." # PAT with Work Items (Read) + Code (Read) aikgraph update ~/projects/my-workspace --project MyProject ``` 发生的过程如下： 1. 工作项和仓库作为带有 YAML frontmatter 的 markdown 被获取到 `/raw/azure/` 中。 2. 每个仓库的默认分支会被浅克隆到 `/raw/azure/repos//` 下。 3. 常规 AST 提取器对克隆的代码运行，Azure 提取器从工作项关系中发出 `parent_of` / `related_to` / `touches_repo` 边，并从仓库到代码符号发出 `contains` 边。 4. 构建的图谱被写入 `~/.kiro/aikgraph-out//` 下（可通过 `AIKGRAPH_OUT=` 覆盖），因此它是全局存在的，而不是位于扫描目录内。 增量状态存储在 `/raw/azure/.azure_sync_state.json` 中 —— 随后的运行仅获取自上次游标以来更改的工作项，并且仅重新获取 HEAD 发生变动的仓库。 | 标志 | 用途 | |------|---------| | `--project ` | 要同步的 Azure DevOps 项目（触发同步所必需） | | `--since YYYY-MM-DD` | 限定首次运行的工作项扫描窗口（默认：过去 365 天） | | `--full` | 忽略已保存的状态；强制进行完整重新扫描和重新克隆 | | `--no-clone` | 跳过 git clone 步骤 —— 仅获取工作项 + 仓库元数据 | | `--repos a,b,c` | 仅克隆此仓库子集（以逗号分隔的名称） | ## AI 助手集成 仅基于 AST 的 `update` 命令是一个更大型 pipeline 中无需 LLM 的子集。**语义**层（跨文件概念边、docs/README 理解、图像/PDF 提取、依据边）在安装了该技能的 AI 编码助手中以 `/aikgraph` 的方式运行。 ### Kiro ``` cd ~/projects/my-project aikgraph kiro install ``` 会安装： - `~/.kiro/skills/aikgraph/SKILL.md`（全局）：教导 Kiro 何时以及如何调用 `aikgraph query "..."`、`aikgraph path "A" "B"`、`aikgraph explain "X"` 及其余 CLI 命令的技能。安装一次；即可被 Kiro 在所有项目中拾取。 - `./.kiro/steering/aikgraph.md`（项目局部）：常驻的 steering 文件，指导 Kiro 在回答架构问题前先关注该项目的 `REPORT.md` - `./.kiro/aikgraph-out/`（项目局部）：`aikgraph update` 写入 `graph.json` 和 `REPORT.md` 的输出目录 从 shell 中运行 `aikgraph update` 以构建/刷新图谱。 ### Claude Code ``` cd ~/projects/my-project aikgraph claude install ``` 会安装： - 指引 Claude Code 关注 `REPORT.md` + graph.json 的 `CLAUDE.md` 部分 - 当代码更改时运行 `aikgraph update` 的 PreToolUse 钩子 - `.claude/aikgraph-out/`：项目局部的输出目录 ### GitHub Copilot CLI ``` cd ~/projects/my-project aikgraph copilot install ``` 准备 `.copilot/aikgraph-out/` 作为输出目录。运行 `aikgraph update` 以填充内容。 ### 卸载 ``` aikgraph uninstall # platform: claude | copilot | kiro ``` ## 命令参考 ### 图谱构建（无需 LLM） ``` aikgraph update # AST extract + rebuild (graph.json + REPORT.md only) aikgraph update --html --svg --obsidian # opt into extra outputs aikgraph update --project # also sync Azure DevOps (work items + repos) [--since YYYY-MM-DD] [--full] [--no-clone] [--repos a,b,c] aikgraph cluster-only # re-cluster an existing graph.json aikgraph watch # auto-rebuild on save (needs watchdog) ``` Azure DevOps 同步需要在环境中设置 `AZURE_DEVOPS_ORG` 和 `AZURE_DEVOPS_PAT`。详情请参见 [同步 Azure DevOps](#sync-azure-devops)。 ### 打开 Obsidian 知识库 在运行了 `aikgraph update --obsidian` 后，在 Obsidian 中将 `/aikgraph-out/obsidian/` 作为知识库打开。你将获得： - 每个图谱节点对应一个笔记，并带有指向每个相连节点的 wikilink (`[[neighbor]]`)。 - 每个社区对应一个 `_COMMUNITY_.md` 概览，列出成员、内聚性、桥接节点和跨社区边。 - `graph.canvas`，用于结构化的按社区分组布局（作为 Obsidian Canvas 打开）。 - `.obsidian/graph.json`，其中包含已接入 Obsidian 内置图谱视图的按社区划分的颜色。 ### 内容摄取 ``` aikgraph add # fetch URL into ./raw, update the graph ``` ### 平台安装程序 ``` aikgraph install --platform claude|copilot|kiro aikgraph claude install|uninstall # per-project CLAUDE.md + PreToolUse hook aikgraph copilot install|uninstall # Copilot CLI skill aikgraph kiro install|uninstall # Kiro skill folder + always-on steering aikgraph hook install|uninstall|status # git post-commit / post-checkout hooks ``` ## 开发 重新构建发行版： ``` python3 -m build # wheel + sdist in dist/ ``` 在修改了 `pyproject.toml` 后强制重新安装： ``` pip install -e . --no-deps --force-reinstall ``` 不使用控制台脚本直接运行： ``` python3 -m aikgraph ```