docs: prerequisites and Ollama setup in §4, RAG primer in §8, gh/Cursor troubleshooting

Made-with: Cursor
2026-04-21 15:32:34 +10:00
parent 73e65c23d5
commit 25de357982
3 changed files with 107 additions and 6 deletions
@@ -36,15 +36,77 @@

 ## 4) Быстрый запуск OpenClaude

-### 4.1 Установка
+### 4.0 Предварительные требования
+
+Для любого сценария нужны **Node.js 18+** и **npm** (идут вместе с официальной сборкой Node).
+
+Проверка:
+
+```bash
+node -v
+npm -v
+```
+
+Дальше по шагам:
+
+1. установить **OpenClaude CLI** (раздел **4.1**);
+2. для **локальных** моделей через Ollama — установить и запустить **Ollama** (раздел **4.2**), затем профиль из **4.3**;
+3. для облака (OpenAI / DeepSeek) достаточно ключей API — см. **4.4** и **4.5**.
+
+Если при запуске OpenClaude появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) и проверьте `rg --version` в том же терминале.
+
+### 4.1 Установка OpenClaude

 ```bash
 npm install -g @gitlawb/openclaude
+openclaude --version
 ```

-Если при запуске появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) в систему и проверьте `rg --version` в том же терминале, где стартуете OpenClaude.
+### 4.2 Установка и запуск Ollama (для локального профиля)

-### 4.2 Локальный Ollama-профиль (бесплатно)
+Сайт проекта: [https://ollama.com](https://ollama.com)
+
+**Linux** (типовой скрипт установки):
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+После установки сервис часто уже включён (`systemctl status ollama`). При необходимости: `sudo systemctl enable --now ollama`.
+
+**macOS** (Homebrew):
+
+```bash
+brew install --cask ollama
+```
+
+**Windows**: установщик с [страницы загрузки](https://ollama.com/download) или:
+
+```powershell
+winget install Ollama.Ollama
+```
+
+Проверка CLI:
+
+```bash
+ollama --version
+```
+
+Убедитесь, что API доступен на `http://127.0.0.1:11434` (на Windows приложение после установки обычно уже поднимает сервер; при сомнении запустите `ollama serve` в отдельном окне терминала).
+
+Скачайте хотя бы одну модель для работы с OpenClaude (пример ниже совпадает с профилем в **4.3**):
+
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+Быстрая проверка генерации:
+
+```bash
+ollama run qwen2.5-coder:7b
+```
+
+### 4.3 Локальный Ollama-профиль (бесплатно)

 macOS / Linux:

@@ -71,7 +133,7 @@ openclaude
 ollama launch openclaude --model qwen2.5-coder:7b
 ```

-### 4.3 OpenAI-профиль
+### 4.4 OpenAI-профиль

 macOS / Linux:

@@ -92,7 +154,7 @@ $env:OPENAI_MODEL="gpt-4o"
 openclaude
 ```

-### 4.4 DeepSeek-профиль
+### 4.5 DeepSeek-профиль

 macOS / Linux:

@@ -228,12 +290,35 @@ direnv allow

 ## 8) Минимальный RAG стек (локально)

+### Что такое RAG
+
+**RAG (Retrieval-Augmented Generation)** — подход, при котором модель отвечает не только из «общих» весов, а **сначала находит релевантные фрагменты в ваших данных** (документы, база знаний, код), подмешивает их в контекст и уже тогда формулирует ответ.
+
+### Из чего состоит RAG-стек
+
+1. **Документы** — `md` / `pdf` / `txt`, wiki, выгрузки и т.д.
+2. **Chunking** — разбиение текста на фрагменты фиксированного размера с перекрытием.
+3. **Embeddings** — векторное представление каждого фрагмента.
+4. **Vector DB** — хранение векторов и поиск ближайших соседей по запросу.
+5. **Retriever** — например MCP-инструмент `search_docs`: достаёт релевантный контекст по вопросу пользователя.
+6. **LLM** — генерирует ответ с учётом найденного контекста (и при желании с явными ссылками на источники).
+
+Плюсы такого контура:
+
+- ответы опираются на **ваши** материалы;
+- обычно **меньше голых галлюцинаций** по фактам из документации;
+- проще **проверять происхождение** ответа (по найденным чанкам и источникам).
+
+### Минимальная локальная конфигурация (этот репозиторий)
+
 Рекомендуемая база:

 - Embeddings: `nomic-embed-text` (через Ollama)
 - Vector DB: Qdrant
 - Retrieval tool: MCP `search_docs`

+Готовый пример скриптов и compose: `docs/rag-mcp-starter/`.
+
 Минимальная схема:

 1. Сложить документы (`md/txt/pdf`)
@@ -369,6 +454,8 @@ gh auth status

 Это самый удобный вариант для GitHub: авторизация один раз и нормальная работа `git pull/push` и `gh`.

+Если **`gh repo view`** или API в другой среде (CI, удалённый агент) возвращают ошибку про отсутствие репозитория, хотя у вас локально всё ок — см. пояснение в `docs/openclaude-with-repositories.md` (раздел «Частые ошибки», подраздел про GitHub CLI).
+
 ### 12.2 Через PAT по HTTPS

 1. Создать Personal Access Token на GitHub (минимальные нужные scopes).