ocrag/README.md

Ocrag - OpenCode 代码知识库 RAG 插件

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

English | 设计文档

---

✨ 特性

• 🚀 零配置：嵌入式数据库，安装即用
• 🔒 本地优先：所有数据存储在本地，不上传到外部服务器
• 🔍 语义搜索：通过自然语言查询相关代码片段
• 📦 多语言支持：支持 Python、Rust、C++、Go、JavaScript、TypeScript 等 40+ 种编程语言
• ⚡ 极速响应：搜索延迟 < 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

# 递归添加整个目录（自动应用 .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 加速：

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/

---

📚 相关文档

• 设计文档 - 详细的设计说明和技术选型分析
• CHANGELOG - 版本更新记录

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License

---

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