代码知识图谱

niuma_code 使用内置 LanguageParser 从你的代码库构建结构化知识图谱。图谱索引符号、定义、引用和依赖关系——让 LLM 无需 grep 即可即时访问代码结构。

工作原理

项目打开时：
  LanguageParser 解析源文件
  → 提取：类、函数、导入、导出
  → 构建：符号表 + 关系图
  → 存储于：.niuma/kg/

知识图谱按需构建——三因素决策避免每次启动全量解析：

因素 条件
检测到文件变更 自上次构建以来有新增/修改/删除文件
时间阈值 距上次构建超过 24 小时
手动触发 用户显式请求重建

4 个检索工具

locate_symbol

查找符号的定义位置：

工具：locate_symbol
输入：{ "name": "UserService" }
输出：{
  "type": "class",
  "file": "app/services/user.py",
  "line": 42,
  "signature": "class UserService(BaseService):"
}

check_file_deps

列出给定文件的所有导入/被导入关系：

工具：check_file_deps
输入：{ "path": "app/services/auth.py" }
输出：{
  "imports_from": ["app/models/user.py", "app/utils/crypto.py"],
  "imported_by": ["app/routes/auth.py", "tests/test_auth.py"]
}

find_references

在代码库中查找符号的所有使用位置：

工具：find_references
输入：{ "name": "login" }
输出：[
  { "file": "app/services/auth.py", "line": 28, "context": "def login(email, password):" },
  { "file": "app/routes/auth.py", "line": 15, "context": "await auth_service.login(email, password)" },
  { "file": "tests/test_auth.py", "line": 42, "context": "result = auth_service.login(...)" }
]

trace_calls

追踪函数的调用链：

工具：trace_calls
输入：{ "name": "handle_login", "depth": 3 }
输出：{
  "call_chain": [
    "handle_login → validate_email",
    "handle_login → auth_service.login → verify_password",
    "handle_login → auth_service.login → create_token"
  ]
}

符号类型索引

LanguageParser 解析以下符号类型：

符号 语言 示例
Class Python, JS/TS class UserService:
Function Python, JS/TS def get_user(id):
Method Python, JS/TS async def verify(token):
Variable Python BASE_URL = "..."
Import Python, JS/TS from app.models import User
Export JS/TS export default handler
Type TypeScript interface Config { ... }

重建决策

知识图谱基于三个因素自动重建：

是否需要重建？
  → 自上次构建以来有文件变更？→ 是 → 重建
  → 距上次构建超过 24 小时？  → 是 → 重建
  → 用户运行 /kg-rebuild？    → 是 → 重建
  → 否则                      → 否 → 使用缓存

缓存位置：项目根目录 .niuma/kg/（默认 git-ignored）。

相比 grep 的优势

方面 grep 知识图谱
查找定义 按名称搜索（可能匹配子串） 基于 AST 节点的精确符号查找
查找引用 grep 搜索字符串模式 语义引用追踪
依赖关系 手动分析 自动导入图
调用链 手动追踪 自动调用图
语言支持 基于模式 基于 AST（语言感知）
速度 扫描所有文件 O(1) 索引查找

支持的语言

通过内置 LanguageParser 提供完整 AST 支持：

使用技巧