songsenand
/
ocrag
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ocrag/README.md

3.9 KiB
Raw Blame History

Ocrag - OpenCode 代码知识库 RAG 插件

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

English | 设计文档

✨ 特性

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

📦 安装

环境要求

  • Python 3.10+
  • uv（包管理器）

安装步骤

# 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/

🚀 快速开始

基本使用

# 添加文件到知识库
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 加速：

USE_GPU=true uv run ocrag search "查询内容"

数据库位置

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

📊 性能

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

运行性能测试：

uv run python scripts/benchmark.py

✅ 运行测试

# 运行所有测试
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 中导出

代码规范

# 格式化代码
ruff format src/

# 代码检查
ruff check src/

📚 相关文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

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