English | 中文

@easbot/codebase

代码知识图谱 SDK - 基于 Property Graph 模型的代码索引与查询系统

特性

• Property Graph 模型: 使用节点和边存储代码实体及其关系
• 多语言支持: TypeScript、JavaScript、Python、Rust、Go、C/C++、C#、Java、Scala、Ruby、PHP、Zig
• 混合搜索: FTS 全文搜索 + 结构化查询
• 增量更新: 基于文件内容哈希的智能增量索引
• Tree-sitter 解析: 高性能 AST 解析

安装

pnpm add @easbot/codebase

快速开始

import { createCodebase } from '@easbot/codebase';

// 创建图谱实例
const graph = await createCodebase({
  workspaceDir: '/path/to/your/project',
});

// 索引项目
const result = await graph.indexDirectory();
console.log(`索引完成: ${result.filesProcessed} 文件, ${result.nodesCreated} 节点`);

// 搜索代码
const results = await graph.search('UserService');
for (const r of results) {
  console.log(`${r.name} (${r.astType}) - ${r.filePath}:${r.startLine}`);
}

// 查询节点
const classes = await graph.queryNodes({ astType: 'class_declaration' });

// 查询调用图
const callGraph = await graph.queryCallGraph('ts:src/service.ts:function_declaration:UserService');

// 关闭图谱
await graph.close();

API 文档

CodeKnowledgeGraph

主类，提供完整的代码知识图谱功能。

构造选项

interface CodeKnowledgeGraphConfig {
  workspaceDir: string;           // 工作区目录
  database?: {
    path: string;                 // 数据库路径
    walMode?: boolean;            // WAL 模式
  };
  parser?: {
    languages?: Language[];       // 支持的语言
    lazyLoad?: boolean;           // 延迟加载
  };
  indexer?: {
    batchSize: number;            // 批处理大小
    ignorePatterns: string[];     // 忽略模式
    incremental: boolean;         // 增量更新
  };
}

主要方法

| 方法 | 说明 | |------|------| | initialize() | 初始化图谱 | | indexFile(path) | 索引单个文件 | | indexDirectory(dir?) | 索引目录 | | sync() | 增量同步 | | search(query, options?) | 混合搜索 | | queryNodes(filter) | 查询节点 | | queryEdges(filter) | 查询边 | | queryNeighbors(nodeId, options?) | 查询邻居 | | queryCallGraph(nodeId, depth?) | 查询调用图 | | queryInheritance(nodeId) | 查询继承关系 | | getStatus() | 获取状态 | | healthCheck() | 健康检查 | | close() | 关闭图谱 |

搜索选项

interface SearchOptions {
  maxResults?: number;            // 最大结果数
  minScore?: number;              // 最小分数
  language?: Language;            // 语言过滤
  filePath?: string;              // 文件路径过滤
  astType?: string;               // AST 类型过滤
  enableFts?: boolean;            // 启用 FTS
  ftsWeight?: number;             // FTS 权重
}

数据模型

节点 (Node)

| 字段 | 类型 | 说明 | |------|------|------| | id | string | 唯一标识 | | name | string | 名称 | | ast_type | string | AST 类型 | | language | string | 语言 | | file_path | string | 文件路径 | | start_line | number | 起始行 | | start_col | number | 起始列 | | end_line | number | 结束行 | | end_col | number | 结束列 | | text | string | 代码文本 |

边 (Edge)

| 字段 | 类型 | 说明 | |------|------|------| | id | string | 唯一标识 | | source | string | 源节点 ID | | target | string | 目标节点 ID | | relation | string | 关系类型 |

关系类型

| 关系 | 说明 | |------|------| | CONTAINS | 包含关系（类包含方法） | | CALLS | 调用关系（函数调用） | | INHERITS_FROM | 继承关系 | | IMPLEMENTS | 实现接口 | | IMPORTS | 导入模块 | | REFERENCES | 引用关系 |

架构

src/
├── types.ts              # 类型定义
├── errors.ts             # 错误类
├── index.ts              # 入口文件
├── code-knowledge-graph.ts  # 主类
├── database/
│   └── database-manager.ts  # 数据库管理
├── parser/
│   └── parser-manager.ts    # 解析器管理
├── extractor/
│   ├── node-extractor.ts    # 节点提取
│   └── edge-extractor.ts    # 边提取
├── indexer/
│   └── indexer.ts           # 索引器
└── query/
    └── query-interface.ts   # 查询接口

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

许可证

MIT