diff --git a/README.md b/README.md index acaabc4..8d7f0e6 100644 --- a/README.md +++ b/README.md @@ -357,3 +357,4 @@ chmod +x script.sh - Быстрый гайд: `docs/quickstart-30min.md` - Готовый starter: `docs/rag-mcp-starter/` +- Работа с GitHub/GitLab/Gitea: `docs/openclaude-with-repositories.md` diff --git a/docs/openclaude-with-repositories.md b/docs/openclaude-with-repositories.md new file mode 100644 index 0000000..573161d --- /dev/null +++ b/docs/openclaude-with-repositories.md @@ -0,0 +1,114 @@ +# OpenClaude и Git-репозитории + +Как организовать работу OpenClaude с GitHub/GitLab/Gitea и похожими сервисами. + +## 1) Что значит "научить OpenClaude работать с репозиториями" + +Обычно это 3 уровня: + +1. **Локальный уровень**: OpenClaude работает в локальном git-репозитории (`clone`, `branch`, `commit`). +2. **Remote уровень**: пуш/PR/issue через токены и CLI (`gh`, `glab`, `tea`). +3. **Контекст и автоматизация**: доступ к данным репозитория через MCP-инструменты. + +## 2) Базовая схема (рекомендуется) + +- Клонировать репозиторий локально. +- Запускать OpenClaude из корня проекта. +- Для GitHub использовать `gh auth login`. +- Для GitLab использовать `glab auth login`. +- Для Gitea использовать SSH-ключи или PAT в remote URL/credential manager. + +Это даёт OpenClaude полный цикл: читать код, редактировать, запускать тесты, делать коммиты и PR. + +## 3) Настройка аутентификации без постоянного ввода пароля + +### GitHub + +```bash +gh auth login +gh auth status +``` + +### GitLab + +```bash +glab auth login +glab auth status +``` + +### Универсально для git HTTPS + +```bash +git config --global credential.helper store +``` + +Лучше и безопаснее - SSH: + +```bash +ssh-keygen -t ed25519 -C "you@example.com" +# добавить публичный ключ в GitHub/GitLab/Gitea +git remote set-url origin git@github.com:OWNER/REPO.git +``` + +## 4) Минимальный безопасный процесс работы с кодом + +1. Создать отдельную feature-ветку. +2. Делать небольшие коммиты с понятными сообщениями. +3. Перед push запускать тесты/lint. +4. Не хранить секреты в репозитории (`.env`, ключи, токены). +5. Для main/master включить protected branch и PR review. + +## 5) Как подключить репозиторий как источник знаний (RAG) + +Если цель - чтобы OpenClaude "знал проект": + +- индексировать `README`, `docs`, ADR, API-контракты, runbook +- не индексировать шум (`node_modules`, `dist`, lock-файлы без необходимости) +- регулярно переиндексировать после merge крупных изменений + +Простой путь: + +- `git clone` репозиторий +- копировать нужные папки в `docs/rag-mcp-starter/docs` +- запускать `index.py` +- использовать `search_docs` и `answer_with_citations` + +## 6) MCP для Git-платформ: что имеет смысл добавить + +Полезные MCP-инструменты: + +- `list_prs(repo)` +- `get_pr_diff(repo, pr_number)` +- `list_issues(repo, label)` +- `create_issue(repo, title, body)` +- `comment_pr(repo, pr_number, body)` +- `get_file_at_ref(repo, path, ref)` + +Такой слой позволяет OpenClaude работать не только с локальным checkout, но и с удаленным контекстом. + +## 7) Практика для self-hosted Git (Gitea/Forgejo/GitLab self-hosted) + +1. Убедиться в доступности API/SSH с сервера. +2. Создать сервисный токен с минимальными правами (least privilege). +3. Хранить токен в переменных окружения или secrets manager. +4. Ограничить доступ по IP/ACL. +5. Вести аудит действий (кто/когда создал PR/comment/push). + +## 8) Частые ошибки + +- OpenClaude запущен не из корня репозитория. +- Нет прав на push в remote. +- PAT истек или не имеет scope для PR/issues. +- Смешивание нескольких аккаунтов в одном credential helper. +- Отсутствуют локальные зависимости проекта (тесты не запускаются). + +## 9) Рабочий чек-лист перед началом + +```bash +git status +git remote -v +gh auth status || true +glab auth status || true +``` + +Если всё ок - можно давать OpenClaude задачи на полный цикл "изменение -> тест -> commit -> PR". diff --git a/docs/rag-mcp-starter/README.md b/docs/rag-mcp-starter/README.md index 0f74367..ea7c58c 100644 --- a/docs/rag-mcp-starter/README.md +++ b/docs/rag-mcp-starter/README.md @@ -6,6 +6,7 @@ - `index.py` - индексация документов в Qdrant - `mcp_server.py` - MCP инструменты `search_docs` и `answer_with_citations` - `requirements.txt` - Python зависимости +- `install.sh` - one-command bootstrap для Ubuntu ## Быстрый запуск @@ -21,6 +22,20 @@ python index.py python mcp_server.py ``` +## Автоматический bootstrap + +```bash +chmod +x install.sh +./install.sh +``` + +Опции: + +```bash +./install.sh --skip-model-pull +./install.sh --docs-dir /path/to/my/docs +``` + ## Переменные окружения - `QDRANT_URL` (default `http://127.0.0.1:6333`) diff --git a/docs/rag-mcp-starter/install.sh b/docs/rag-mcp-starter/install.sh new file mode 100755 index 0000000..e06122f --- /dev/null +++ b/docs/rag-mcp-starter/install.sh @@ -0,0 +1,108 @@ +#!/usr/bin/env bash +set -euo pipefail + +# One-command bootstrap for OpenClaude local RAG starter on Ubuntu. +# +# Usage: +# ./install.sh +# ./install.sh --skip-model-pull +# ./install.sh --docs-dir /path/to/docs + +SKIP_MODEL_PULL=0 +DOCS_DIR="${PWD}/docs" +WORKDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +while [[ $# -gt 0 ]]; do + case "$1" in + --skip-model-pull) + SKIP_MODEL_PULL=1 + shift + ;; + --docs-dir) + DOCS_DIR="$2" + shift 2 + ;; + *) + echo "Unknown argument: $1" + exit 2 + ;; + esac +done + +need_cmd() { + command -v "$1" >/dev/null 2>&1 || { + echo "Missing command: $1" + exit 1 + } +} + +echo "==> Installing system packages" +sudo apt update +sudo apt install -y curl git docker.io docker-compose-plugin python3 python3-venv python3-pip + +echo "==> Enabling Docker" +sudo systemctl enable docker +sudo systemctl start docker + +echo "==> Installing Ollama if needed" +if ! command -v ollama >/dev/null 2>&1; then + curl -fsSL https://ollama.com/install.sh | sh +fi +sudo systemctl enable ollama +sudo systemctl start ollama + +echo "==> Verifying local services" +curl -fsS "http://127.0.0.1:11434/api/tags" >/dev/null || true + +echo "==> Installing OpenClaude CLI" +if ! command -v openclaude >/dev/null 2>&1; then + need_cmd npm + npm install -g @gitlawb/openclaude +fi + +echo "==> Starting Qdrant" +cd "$WORKDIR" +docker compose up -d + +echo "==> Creating Python venv" +python3 -m venv .venv +source .venv/bin/activate +pip install --upgrade pip +pip install -r requirements.txt + +echo "==> Preparing docs directory" +mkdir -p "$DOCS_DIR" +if [[ "$DOCS_DIR" != "${WORKDIR}/docs" ]]; then + echo "Using custom docs directory: $DOCS_DIR" +fi + +if [[ "$SKIP_MODEL_PULL" -eq 0 ]]; then + echo "==> Pulling models (qwen2.5-coder:7b + nomic-embed-text)" + ollama pull qwen2.5-coder:7b + ollama pull nomic-embed-text +else + echo "==> Skipping model pull (--skip-model-pull)" +fi + +cat <