# Kinode

**Repository Path**: twzxzl/kinode

## Basic Information

- **Project Name**: Kinode
- **Description**: Kino code 
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kinode

**AI 代码知识图谱工具** - 基于 Java 的 GitNexus 复刻版本

Kinode 是一个为 AI 编程助手设计的代码理解工具，通过构建代码知识图谱，帮助 AI 理解代码结构、调用关系和执行流程。

## 特性

- **可视化 WebUI**: 基于 Cytoscape.js 的交互式代码知识图谱浏览器
- **仓库管理**: 通过 Web 界面添加、查看、重建代码仓库索引
- **代码解析**: 支持 Java 语法解析，提取类、方法、字段等代码符号
- **知识图谱**: 基于 Neo4j Embedded 构建代码关系图
- **混合检索**: BM25 全文搜索 + 向量语义检索，RRF 融合排序
- **MCP 服务**: 兼容 Model Context Protocol，可集成 Cursor、Windsurf 等 AI 编辑器
- **增量同步**: 基于 Git commit 自动检测变更，增量更新索引
- **向量化节省**: 基于文件内容 hash 跳过未变更文件的向量化调用

## 系统要求

- **JDK 17+**
- **Maven 3.6+**
- 可选: OpenAI API Key（用于向量嵌入）

## 快速开始

### 1. 编译打包

```bash
cd kinode
mvn package -DskipTests
```

### 2. 启动服务

```bash
java -jar target/kinode-1.0-SNAPSHOT.jar
```

服务启动后会自动打开浏览器访问 WebUI（http://localhost:12222）。

### 3. 通过 WebUI 管理仓库

启动后，你可以通过直观的 Web 界面完成所有操作：

- **添加仓库**: 点击"➕ 添加仓库"按钮，输入 Git 仓库路径即可自动索引
- **查看图谱**: 点击仓库的"查看图谱"按钮，可视化浏览代码知识结构
- **搜索节点**: 在搜索框输入关键词，快速定位类、方法等代码符号
- **重建索引**: 代码变更后，点击"🔄 重建索引"按钮更新索引

### 4. 启动 MCP 服务（可选）

如需与 AI 编辑器集成，启动 MCP 服务：

```bash
java -jar target/kinode-1.0-SNAPSHOT.jar mcp
```

## MCP 工具

Kinode 提供 7 个核心 MCP 工具，兼容 GitNexus 接口规范：

### 1. `list_repos` - 列出仓库
列出所有已索引的代码仓库及其统计信息。

### 2. `query` - 混合检索
```
query(query, taskContext, goal, limit, symbolsPerProcess, includeSource, repo)
```
- **query**: 搜索关键词或自然语言描述
- **taskContext**: 任务上下文，帮助优化排序
- **goal**: 查找目标
- **limit**: 最大返回流程数
- **includeSource**: 是否包含源代码

### 3. `context` - 符号上下文
```
context(name, uid, filePath, includeSource, repo)
```
获取符号的 360° 完整视图：调用者、被调用者、所属文件、关联提交。

### 4. `impact` - 影响范围分析
```
impact(symbol, direction, maxDepth, relationTypes, includeTests, minConfidence, repo)
```
分析修改代码符号的影响范围（爆炸半径）。

### 5. `detect_changes` - 变更检测
```
detect_changes(scope, compareTo, repo)
```
分析 Git 工作区变更，找出受影响的执行流程。

### 6. `rename` - 图感知重命名
```
rename(oldName, uid, newName, filePath, dryRun, repo)
```
基于代码图的多文件协调重命名，预览模式安全可控。

### 7. `cypher` - 原生图查询
```
cypher(query, repo)
```
直接执行 Cypher 语句查询代码知识图谱。

## 配置

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | OpenAI API Key（向量嵌入） | - |
| `CLOUD_PARSER_URL` | 云端解析服务地址 | - |

### 配置文件 (`application.yml`)

```yaml
kinode:
  storage:
    data-dir: ${user.home}/.kinode    # 数据存储目录
    
  embedding:
    enabled: true                      # 启用向量嵌入
    provider: openai                   # 提供商
    api-key: ${OPENAI_API_KEY:}       # API Key
    model: text-embedding-3-small     # 模型
    
  cloud-parser:
    enabled: false                     # 启用云端解析（JS/TS）
    url: ${CLOUD_PARSER_URL:}
```

## 数据存储

所有索引数据存储在 `~/.kinode/` 目录：

```
~/.kinode/
├── neo4j/           # Neo4j 图数据库
├── lucene/          # Lucene 全文索引
└── registry.json    # 仓库注册表
```

## 增量同步

Kinode 内置定时调度器，自动检测代码变更并增量更新：

- **启动延迟**: 5 分钟
- **检查周期**: 每 5 分钟
- **检测方式**: 比较 Git commit 与上次同步的 commit
- **更新策略**: 仅对变更文件执行删除+重建

## 集成 AI 编辑器

### Cursor / Windsurf

在项目 `.cursor/mcp.json` 或全局配置中添加：

```json
{
  "mcpServers": {
    "kinode": {
      "command": "java",
      "args": ["-jar", "/path/to/kinode-1.0-SNAPSHOT.jar", "mcp"]
    }
  }
}
```

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "kinode": {
      "command": "java",
      "args": ["-jar", "/path/to/kinode-1.0-SNAPSHOT.jar", "mcp"]
    }
  }
}
```

## 技术栈

| 组件 | 技术 |
|------|------|
| 框架 | Spring Boot 3.2 |
| MCP 协议 | Spring AI MCP 1.0.0-M6 |
| 图数据库 | Neo4j Embedded 5.15 |
| 全文搜索 | Apache Lucene 9.7 |
| Java 解析 | JavaParser 3.25 |
| Git 操作 | JGit 6.8 |
| WebUI | 原生 HTML5 + Cytoscape.js |

## 架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     WebUI (浏览器)                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ 仓库管理    │  │ 图谱可视化  │  │ 代码搜索                │  │
│  │ - 添加仓库  │  │ - 节点浏览  │  │ - 关键词搜索            │  │
│  │ - 重建索引  │  │ - 关系展示  │  │ - 调用链分析            │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────────┘
                          │ HTTP API
┌─────────────────────────▼───────────────────────────────────────┐
│                    Kinode Spring Boot Server                     │
├─────────────────────────────────────────────────────────────────┤
│  REST API: /api/repos | /api/repo/*                             │
├─────────────────────────────────────────────────────────────────┤
│  MCP Tools: query | context | impact | rename | ...             │
├─────────────────────────────────────────────────────────────────┤
│              IndexPipeline (索引管道)                            │
├──────────────┬──────────────┬──────────────────────────────────┤
│  Neo4j       │   Lucene     │   Embedding                      │
│  (图存储)    │   (BM25)     │   (向量)                         │
└──────────────┴──────────────┴──────────────────────────────────┘
```

## WebUI 功能

### 仓库管理
- **添加仓库**: 输入 Git 仓库路径，自动验证并执行全量索引
- **查看统计**: 显示每个仓库的文件数、节点数、边数
- **重建索引**: 删除旧索引并重新构建，适用于代码大幅变更后

### 图谱可视化
- **交互式浏览**: 点击节点展开子节点（文件 → 类 → 方法）
- **关系展示**: 自动显示 DEFINES、CONTAINS、CALLS、USES 等关系
- **节点定位**: 双击空白处自动适应视图

### 代码搜索
- **关键词搜索**: 支持类名、方法名模糊匹配
- **调用链分析**: 
  - 查看方法引用的类（USES 关系）
  - 查看方法的调用者（CALLERS 关系）
- **结果高亮**: 搜索结果在图谱中高亮显示

## 开发

### 运行测试

```bash
mvn test
```

### 本地调试

```bash
# 编译
mvn compile

# 启动服务（带 WebUI）
mvn spring-boot:run
```

## 许可证

MIT License