209 lines
4.5 KiB
Markdown
209 lines
4.5 KiB
Markdown
# Ocrag - OpenCode 代码知识库 RAG 插件
|
||
|
||
> 为 OpenCode 提供本地代码语义搜索能力，支持将代码文件添加到知识库并通过自然语言进行检索。
|
||
|
||
[English](./README_EN.md) | [设计文档](./DescriptionOfDesign.md)
|
||
|
||
---
|
||
|
||
## ✨ 特性
|
||
|
||
- 🚀 **零配置**：嵌入式数据库，安装即用
|
||
- 🔒 **本地优先**：所有数据存储在本地，不上传到外部服务器
|
||
- 🔍 **语义搜索**：通过自然语言查询相关代码片段
|
||
- 📦 **多语言支持**：支持 Python、Rust、C++、Go、JavaScript、TypeScript 等 40+ 种编程语言
|
||
- ⚡ **极速响应**：搜索延迟 < 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
|
||
|
||
# 递归添加整个目录（自动应用 .gitignore + 二进制文件过滤）
|
||
uv run ocrag add ./src/ --recursive
|
||
|
||
# 排除特定文件
|
||
uv run ocrag add ./src/ --recursive --exclude "**/__pycache__" "**/test_*.py"
|
||
|
||
# 只添加特定类型的文件
|
||
uv run ocrag add ./src/ --recursive --include "*.py" "*.rs"
|
||
|
||
# 禁用 .gitignore 过滤
|
||
uv run ocrag add ./src/ --recursive --no-ignore
|
||
|
||
# 搜索相关代码
|
||
uv run ocrag search "如何实现用户认证"
|
||
|
||
# 列出知识库中的文件
|
||
uv run ocrag list
|
||
|
||
# 使用通配符筛选列表
|
||
uv run ocrag list "*.py" # 仅列出 Python 文件
|
||
uv run ocrag list "src/**" # 仅列出 src 目录下的文件
|
||
|
||
# 删除文件
|
||
uv run ocrag remove ./src/main.py
|
||
|
||
# 使用通配符批量删除
|
||
uv run ocrag remove "**/test_*.py" # 删除所有测试文件
|
||
uv run ocrag remove "src/**/*.js" # 删除 src 下所有 JS 文件
|
||
```
|
||
|
||
### 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日
|