# opencode-rag

**Repository Path**: hivedark/opencode-rag

## Basic Information

- **Project Name**: opencode-rag
- **Description**: 基于 MCP Local RAG 的本地知识库项目，用于文档语义检索和问答
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-28
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode RAG

基于 MCP Local RAG 的本地知识库项目，用于文档语义检索和问答。支持 PDF、DOCX、Markdown 等多种文档格式的语义搜索。

## 什么是 RAG

检索增强生成（Retrieval-Augmented Generation，RAG）是一种解决大语言模型"幻觉"和私有知识库适配的核心技术。

**工作流程：**
1. 将私有数据拆解为语义片段，通过嵌入模型转化为向量存储在向量数据库
2. 用户提问时，先从向量库检索相关文本片段
3. 将这些片段作为上下文输入 LLM，生成基于真实数据源的回答

**优点：**
- 低成本：无需训练模型，只需更新向量库即可同步最新知识
- 避免遗忘：不会像微调那样导致模型"遗忘"已有知识
- 多数据源适配：灵活对接 PDF、Markdown、数据库等多种数据源
- 准确可溯源：确保内容准确性和答案可追溯

## 项目架构

```
┌─────────────────────────────────────────────────────────────┐
│                        用户提问                              │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                      MCP Local RAG                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐ │
│  │   查询处理   │───▶│  向量检索    │───▶│  上下文组装     │ │
│  └─────────────┘    └─────────────┘    └─────────────────┘ │
│                           │                      │          │
│                           ▼                      ▼          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐ │
│  │  嵌入模型    │    │ LanceDB     │    │   LLM 生成      │ │
│  │ (all-MiniLM │    │ (向量存储)  │    │   (如 OpenCode) │ │
│  │   L6-v2)    │    │             │    │                 │ │
│  └─────────────┘    └─────────────┘    └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                        知识库文档                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  docs/      │  │   PDF       │  │   TXT/MD    │         │
│  │  rag.docx   │  │             │  │             │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

## 项目结构

```
docs/
├── rag.docx            # RAG 技术解析
└── minix-token-plan.md # MiniMax Token Plan 套餐说明

models/                  # 嵌入模型存储
└── all-MiniLM-L6-v2/   # Sentence Transformers 模型

lancedb/                # 向量数据库存储

.opencode/              # OpenCode 配置
├── package.json
└── skills/mcp-local-rag/  # RAG 技能配置

AGENTS.md               # Agent 行为指南
dowload_model.py        # 模型下载脚本
README.md               # 项目说明
```

## 快速开始

### 1. 安装依赖

```bash
npm install -g mcp-local-rag --registry=https://registry.npmmirror.com
```

### 2. 下载模型

运行脚本下载嵌入模型：

```bash
python dowload_model.py
```

或手动下载 `sentence-transformers/all-MiniLM-L6-v2` 模型到 `models/` 目录。

### 3. 构建知识库

摄入文档到向量数据库：

```bash
npx -y mcp-local-rag --cache-dir ./models --db-path ./lancedb --model-name all-MiniLM-L6-v2 ingest "docs/rag.docx"
```

### 4. 查询测试

```bash
# 查询知识库
npx -y mcp-local-rag --cache-dir ./models --db-path ./lancedb --model-name all-MiniLM-L6-v2 query "你的问题"

# 查看知识库状态
npx -y mcp-local-rag --cache-dir ./models --db-path ./lancedb --model-name all-MiniLM-L6-v2 status

# 查看已摄入的文件
npx -y mcp-local-rag --cache-dir ./models --db-path ./lancedb --model-name all-MiniLM-L6-v2 list
```

## 常用命令

| 命令 | 说明 |
|------|------|
| `ingest` | 摄入文档到知识库 |
| `query` | 查询知识库 |
| `list` | 列出已摄入的文件 |
| `status` | 查看知识库状态 |
| `delete` | 从知识库删除文件 |

更多命令选项参考 [.opencode/skills/mcp-local-rag/references/cli-reference.md](.opencode/skills/mcp-local-rag/references/cli-reference.md)

## 配置说明

- **模型路径**: `./models`
- **数据库路径**: `./lancedb`
- **模型名称**: `all-MiniLM-L6-v2` (轻量级 Sentence Transformers 模型)
- **搜索模式**: 混合搜索 (向量 + 关键词)

## 相关文档

- [CLI 参考](.opencode/skills/mcp-local-rag/references/cli-reference.md)
- [查询优化](.opencode/skills/mcp-local-rag/references/query-optimization.md)
- [结果精炼](.opencode/skills/mcp-local-rag/references/result-refinement.md)

## 记忆系统 (WorkLog Skill)

本项目集成了 WorkLog Skill 用于个人工作日志与知识管理，帮助减少 token 消耗并提供上下文感知的回复。

### 核心功能

- 记录每日工作内容和进展
- 保存问题解决过程和方案
- 整理技术研究和学习笔记
- 快速检索历史记录

### 特殊指令

| 指令 | 功能 | 示例 |
|------|------|------|
| `/save [内容]` | 快速保存到记忆 | `/save 完成用户认证模块` |
| `/remember [关键词]` | 搜索相关记忆 | `/remember OAuth` |
| `/recall` | 列出最近记忆 | `/recall` |
| `/log [类型] [内容]` | 分类记录 | `/log problem 登录超时` |

### 存储位置

```
~/.worklogs/
├── daily/           # 每日工作日志 (YYYY-MM-DD.md)
├── problems/        # 问题解决记录
├── research/        # 技术研究笔记
├── changes/        # 代码改动记录
└── quick.md        # 快速记录
```

### Grep 检索

```bash
# 搜索相关内容
Grep pattern="分布" path="~/.worklogs"

# 搜索特定分类
Grep pattern="bug" path="~/.worklogs/problems"
Grep pattern="research" path="~/.worklogs/research"
```

### 使用场景

1. **回答问题前**：使用 `/remember [关键词]` 检索相关记忆，减少 token 消耗
2. **完成任务后**：及时记录工作内容和解决方案
3. **遇到问题时**：记录问题背景、解决思路、关键代码
4. **定期整理**：每周回顾并归类重要记录