# Ocrag - OpenCode 代码知识库 RAG 插件

> 为 OpenCode 提供本地代码语义搜索能力，支持将代码文件添加到知识库并通过自然语言进行检索。

[English](./README_EN.md) | [设计文档](./DescriptionOfDesign.md)

---

## ✨ 特性

- 🚀 **零配置**：嵌入式数据库，安装即用
- 🔒 **本地优先**：所有数据存储在本地，不上传到外部服务器
- 🔍 **语义搜索**：通过自然语言查询相关代码片段
- 📦 **多语言支持**：支持 Python、Rust、C++、Go、JavaScript、TypeScript 等 29 种编程语言
- ⚡ **极速响应**：搜索延迟 < 100ms
- 🤖 **AI 友好**：输出格式专为 AI 消费设计

---

## 📦 安装

### 环境要求

- Python 3.10+
- [uv](https://github.com/astral-sh/uv)（包管理器）

### 安装步骤

```bash
# 1. 安装 Python 包
uv pip install -e .

# 2. 安装 OpenCode 插件（可选）
cp opencode-plugin/ocrag-plugin.ts ~/.config/opencode/plugins/

# 3. 安装 Skill（可选）
mkdir -p ~/.config/opencode/skills/ocrag
cp opencode-skill/SKILL.md ~/.config/opencode/skills/ocrag/
```

---

## 🚀 快速开始

### 基本使用

```bash
# 添加文件到知识库
uv run ocrag add ./src/main.py

# 递归添加整个目录
uv run ocrag add ./src/ --recursive

# 搜索相关代码
uv run ocrag search "如何实现用户认证"

# 列出知识库中的文件
uv run ocrag list

# 删除文件
uv run ocrag remove ./src/main.py
```

### OpenCode 集成

安装插件后，AI 可以自动使用知识库功能：

```
用户：把当前文件加入知识库
AI：✓ 已将 main.py 添加到知识库

用户：认证模块是怎么实现的？
AI：根据知识库中的代码，认证模块包含以下关键实现...
```

---

## 📁 项目结构

```
ocrag/
├── src/ocrag/              # Python 源代码
│   ├── cli.py             # 命令行入口
│   ├── chunker.py         # 代码分块
│   ├── embedder.py        # 向量化模块
│   ├── db.py              # 数据库操作
│   └── commands/          # 命令实现
│       ├── add.py
│       ├── search.py
│       ├── remove.py
│       └── list.py
├── models/                # Embedding 模型
│   └── Qwen3-Embedding-0.6B/
├── tests/                 # 单元测试
├── scripts/               # 工具脚本
│   └── benchmark.py       # 性能测试
├── opencode-plugin/      # OpenCode 插件
└── opencode-skill/       # Skill 文件
```

---

## 🔧 配置

### 模型配置

默认使用 `models/Qwen3-Embedding-0.6B` 本地模型。

如需使用 GPU 加速：
```bash
USE_GPU=true uv run ocrag search "查询内容"
```

### 数据库位置

数据默认存储在 `~/.ocrag/data.lance`

---

## 📊 性能

| 操作 | 延迟 | 说明 |
|------|------|------|
| 搜索 | **~65ms** | 含 embedding + 向量检索 |
| 添加文件 | **~5s** | 含分块 + embedding + 存储 |
| 列出文件 | **~5ms** | 纯数据库查询 |

运行性能测试：
```bash
uv run python scripts/benchmark.py
```

---

## ✅ 运行测试

```bash
# 运行所有测试
uv run python -m pytest

# 运行特定模块测试
uv run python -m pytest tests/unit/test_db.py -v

# 查看测试覆盖
uv run python -m pytest --cov=src/ocrag
```

---

## 🛠️ 开发

### 添加新命令

1. 在 `src/ocrag/commands/` 下创建新文件
2. 实现 `run()` 函数
3. 在 `src/ocrag/cli.py` 中注册命令
4. 在 `src/ocrag/commands/__init__.py` 中导出

### 代码规范

```bash
# 格式化代码
ruff format src/

# 代码检查
ruff check src/
```

---

## 📚 相关文档

- [设计文档](./DescriptionOfDesign.md) - 详细的设计说明和技术选型分析
- [CHANGELOG](./CHANGELOG.md) - 版本更新记录

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📄 许可证

MIT License

---

**版本**：0.1.0  
**最后更新**：2026年4月15日