Skip to content

code-knowledge-map-generator.md

Latest commit

 

History

History
160 lines (126 loc) · 4.92 KB

code-knowledge-map-generator.md

File metadata and controls

160 lines (126 loc) · 4.92 KB

AI 代码库知识地图生成器

自动分析代码库，生成交互式知识地图，让新成员快速理解架构

功能设计

核心功能

  • 架构可视化 - 自动识别核心模块、依赖关系、调用链路，生成 Mermaid/Graphviz 图
  • 关键节点标注 - 标记入口文件、配置中心、核心业务逻辑、高频修改区域
  • 问答式探索 - "这个模块做什么？" "数据流怎么走？" 直接向地图提问
  • 版本对比 - PR 合并后自动更新地图，高亮变更影响范围

辅助功能

  • 支持多语言（通过 Tree-sitter）
  • GitHub Actions 集成，push 触发更新
  • 导出为 PNG/SVG/PDF

技术方案

数据层

代码仓库 → Git Clone
    ↓
AST 解析器 (Tree-sitter)
    ↓
依赖图提取 (imports/exports 分析)
    ↓
图存储 (MVP: 内存图 / 生产: Neo4j 可选)

逻辑层

graph-service/
├── parser.ts        # AST 解析，提取节点
├── analyzer.ts      # 依赖分析，构建图
├── ranker.ts        # PageRank 找核心节点
└── diff.ts          # 版本对比，增量更新

ai-service/
├── embedder.ts      # 代码片段向量化
├── qna.ts           # 问答接口 (RAG)
└── summarizer.ts    # 模块摘要生成

展示层

Web 前端 (React + D3.js / Cytoscape.js)
├── 交互式图谱视图
├── 节点详情面板
├── 问答对话框
└── 版本对比视图

RAG 代码切分策略

针对代码问答的切分方案：

  1. 优先按函数/类切分 - 利用 AST 识别语义边界，每个函数/类作为一个 chunk
  2. 保留上下文 - 每个 chunk 包含：文件路径 + 类名 + 函数签名 + import 列表
  3. 滑动窗口兜底 - 对于过大的函数（>500行），使用 200 行窗口、50 行重叠
  4. 元数据增强 - 存储：调用者列表、被调用者列表、所属模块

幻觉控制机制：

  • 问答时仅基于检索到的代码片段回答
  • 明确标注信息来源（文件:行号）
  • 无法确定时返回"未找到相关代码"

版本对比算法

影响范围定义：

  1. 直接影响 - 变更文件本身
  2. 一级依赖 - import 了变更文件的所有模块
  3. 传递依赖 - 通过依赖链可到达的模块（默认深度 3 层）

算法流程：

1. Git Diff 获取变更文件列表
2. 从依赖图中查找每个变更文件的所有入边（被谁依赖）
3. 递归遍历入边，记录影响路径
4. 标记影响层级（直接/一级/传递）
5. 在图谱中高亮显示影响范围

性能基准

指标 目标值 测试条件
小型仓库 < 30s < 100 文件，< 10K 行
中型仓库 < 2min < 1000 文件，< 100K 行
大型仓库 < 5min < 5000 文件，< 500K 行
增量更新 < 10s 单文件变更
问答响应 < 3s 首次查询（含向量化）

优化策略：

  • 增量解析：只处理变更文件
  • 懒加载：按需加载子图
  • 缓存：向量结果缓存 24h

实现步骤

Phase 1: MVP (3-4 周)

  1. 实现单语言支持（JS/TS）
  2. 基础依赖图生成（import 语句解析）
  3. 简单 Web UI 展示图谱
  4. GitHub Action 触发更新
  5. MVP 技术栈简化：内存图 + 内存向量存储（不依赖外部数据库）

Phase 2: 智能化 (2 周)

  1. 代码向量化 + 相似度检索
  2. 模块自动摘要生成
  3. PageRank 识别核心节点
  4. 问答功能集成（含幻觉控制）

Phase 3: 增强功能 (2 周)

  1. 多语言支持（Python, Go, Java, Rust）
  2. 版本对比功能（含影响范围算法）
  3. 导出功能（PNG/SVG/PDF）
  4. 可选：外部数据库支持（Neo4j、Pinecone）

资源需求

API & 服务

  • LLM API - OpenAI / Claude / GLM（摘要生成、问答）
  • 向量存储 - MVP: 内存（Map + 余弦相似度）/ 生产: Pinecone / Milvus（可选）
  • 图存储 - MVP: 内存（邻接表）/ 生产: Neo4j（可选）

开源依赖

  • tree-sitter - 多语言 AST 解析
  • @babel/parser - JS/TS 深度解析
  • cytoscape.js 或 react-force-graph - 图可视化
  • langchain - RAG 问答链

部署

  • GitHub App 或 GitHub Action
  • 可选：Vercel / Cloudflare Pages 托管前端

风险与缓解

风险 缓解措施
大型仓库解析性能 增量更新 + 懒加载 + 性能基准监控
Token 消耗大 只向量化关键节点（PageRank Top 50%）
企业代码隐私 支持自托管 + 私有 LLM
RAG 幻觉问题 来源标注 + 不确定时明确告知

变现建议

  • 开源版 - 公开仓库免费使用，建立社区
  • Pro 版 - 私有仓库支持，$9/月（参考：Sourcegraph Cody $9/月）
  • Team 版 - 团队协作功能，$19/月/用户
  • Enterprise - 自托管 + SSO + SLA，定制报价

参考 Issue

Closes #15

Created by: AI Ideas Bot Date: 2026-03-22 Updated: 2026-03-22 (根据 Review 反馈优化)