diff --git a/README.md b/README.md index b23619e..c016599 100644 --- a/README.md +++ b/README.md @@ -1,126 +1,36 @@ # opencode-config -Personal opencode setup — Docker-based AI coding assistant with persistent memory plugin and pipeline automation. +Personal opencode setup — Docker-based AI coding assistant with pipeline automation. -## Russian +## Русский -### Quick start +### Быстрый старт ```bash git clone https://github.com/slaid098/opencode-config.git cd opencode-config -cp .env.example .env # заполнить ключи (см. Configuration) +cp .env.example .env docker compose up -d ``` -Доступ: http://localhost:4096. Память инициализируется автоматически при первом старте контейнера. +Доступ: http://localhost:4096 -### Structure +### Структура | Путь | Описание | |------|----------| -| `AGENTS.md` | Глобальные правила оркестратора (главный агент = только план) | -| `.opencode/` | Конфигурация проекта (auto-discovered, без env var) | -| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) | -| `.opencode/skills/` | Skill definitions (14 skills) | -| `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) | -| `src/` | Python RAG CLI (memory) | +| `AGENTS.md` | Глобальные правила оркестратора | +| `.opencode/` | Конфигурация проекта | +| `.opencode/agents/` | Определения subagent'ов | +| `.opencode/skills/` | Определения skills (14 skills) | +| `.opencode/scripts/` | Python скрипты (pipeline-status, spec-status) | +| `src/` | Python RAG CLI | | `docs/` | Handoffs, ADRs, project map | +| `docker-compose.yml` | Docker compose конфиг | -### Configuration +### Конфигурация -Скопируйте `.env.example` → `.env` и заполните. Не-memory переменные: - -| Variable | Default | Description | -|----------|---------|-------------| -| `AI_PROVIDER_BASE_URL` | — (required) | URL API AI-провайдера | -| `AI_PROVIDER_API_KEY` | — (required) | Ключ API AI-провайдера | -| `OPENCODE_SERVER_PASSWORD` | — (required) | Пароль сервера opencode | -| `GITHUB_TOKEN` | — (required) | GitHub personal access token | -| `CONTEXT7_API_KEY` | — (optional) | Context7 MCP API key | -| `ANTIDETECT_BROWSER_MCP_URL` | `http://localhost:8765/mcp` | Antidetect browser MCP URL (optional) | - -Memory-переменные — в секции [Memory setup → Environment variables](#environment-variables-1). - -### Memory setup - -Плагин `@mathew-cf/opencode-memory` — гибридный поиск: ripgrep (keyword) + cloud embeddings (OpenRouter Qwen3 8B, 4096 dim, $0.01/M tokens). - -#### How it works - -``` -opencode (plugin) → rag.js wrapper → python3 -m src.memory → OpenRouter API - ↘ ripgrep (keyword search, parallel) -``` - -`memory_search` параллельно: ripgrep + embeddings, merge по score. `memory_save` коммитит + auto-push + incremental reindex (~1 sec). Первый full reindex: ~4 min для 78 файлов. - -#### Prerequisites - -1. Fork [`slaid098/opencode-memory`](https://github.com/slaid098/opencode-memory) → ваш GitHub -2. OpenRouter API key ([openrouter.ai](https://openrouter.ai), Qwen3 8B = $0.01/M tokens) -3. Заполнить `.env` (см. Configuration + Environment variables ниже) - -#### Initialize - -Docker (рекомендуется): `docker compose up -d` — авто-инициализация через `memory-setup` tool. -Повтор вручную: - -```bash -docker exec opencode /root/.config/opencode/scripts/setup-memory.sh -``` - -Bare metal: `uv sync && .opencode/scripts/setup-memory.sh`. - -#### setup-memory.sh steps - -Скрипт идемпотентный (безопасно перезапускать): - -1. Create `OPENCODE_MEMORY_DIR` if missing -2. Clone memory repo (or `pull --ff-only` if exists) -3. Verify remote origin matches `OPENCODE_MEMORY_REMOTE` -4. Install post-commit hook (auto-push on `memory_save`) -5. Build RAG index if `.rag/index.json` missing (full reindex, ~4 min) -6. Generate JS wrapper at `rag.js` (delegates to Python CLI; original backed up to `.orig`) - -#### Verify - -```bash -cat node_modules/@mathew-cf/rag-cli/bin/rag.js # Python shim ~10 lines, not Rust binary (71) -cat $OPENCODE_MEMORY_DIR/.rag/meta.json | python3 -m json.tool | head -5 # version + sha256 -ls -la $OPENCODE_MEMORY_DIR/.rag/ # index.json + meta.json + .lock (no index.bin) -``` - -```bash -node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind mount" \ - -i $OPENCODE_MEMORY_DIR/.rag -k 3 --json -``` - -#### Troubleshooting - -| Симптом | Причина | Fix | -|---------|---------|-----| -| `Semantic search is unavailable` | Wrapper не сгенерирован / rag-cli не установлен | Re-run `setup-memory.sh` | -| Результаты без scores | Rust rag-cli (old wrapper) | Проверить `rag.js` = Python shim; re-run `setup-memory.sh` | -| `Index version mismatch` при каждом запуске | meta.json missing/stale | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run | -| `OPENAI_BASE_URL env var not set` | `.env` не загружен | Docker: `docker compose up -d --force-recreate`; bare: `.env` в CWD | -| 429 rate limit от OpenRouter | Batch too large / too fast | Уменьшить `OPENAI_EMBEDDING_BATCH_SIZE` (default 50, max 100) | -| Stale Rust artifacts (`index.bin`) | Миграция со старого rag-cli | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run `setup-memory.sh` | - -#### Environment variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `OPENCODE_MEMORY_DIR` | `/root/.local/share/opencode/opencode-memory` | Расположение memory repo | -| `OPENCODE_MEMORY_REMOTE` | — (required) | Git remote для вашего fork opencode-memory | -| `OPENAI_BASE_URL` | — (required) | URL embeddings API (OpenRouter: `https://openrouter.ai/api/v1`) | -| `OPENAI_API_KEY` | — (required) | OpenRouter API key | -| `OPENAI_EMBEDDING_MODEL` | `qwen/qwen3-embedding-8b` | Embedding model (4096 dim) | -| `OPENAI_EMBEDDING_BATCH_SIZE` | `50` | Chunks per API call (OpenRouter max 100) | -| `MEMORY_CHUNK_SIZE` | `512` | Размер chunk в символах | -| `MEMORY_CHUNK_OVERLAP` | `64` | Overlap между chunks | -| `MEMORY_WRAPPER_PATH` | (auto) | Override rag.js wrapper path (for tests) | -| `MEMORY_WRAPPER_PYTHON` | (auto) | Override Python binary для wrapper (for tests) | +Скопируйте `.env.example` → `.env`, заполните ключи. ## English @@ -129,119 +39,29 @@ node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind moun ```bash git clone https://github.com/slaid098/opencode-config.git cd opencode-config -cp .env.example .env # fill in keys (see Configuration) +cp .env.example .env docker compose up -d ``` -Access at http://localhost:4096. Memory initializes automatically on first container start. +Access at http://localhost:4096 ### Structure | Path | Description | |------|-------------| -| `AGENTS.md` | Global orchestrator rules (main agent = plan only) | -| `.opencode/` | Project-local config (auto-discovered, zero env var) | -| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) | +| `AGENTS.md` | Global orchestrator rules | +| `.opencode/` | Project configuration | +| `.opencode/agents/` | Subagent definitions | | `.opencode/skills/` | Skill definitions (14 skills) | | `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) | -| `src/` | Python RAG CLI (memory) | +| `src/` | Python RAG CLI | | `docs/` | Handoffs, ADRs, project map | +| `docker-compose.yml` | Docker compose config | ### Configuration -Copy `.env.example` → `.env` and fill in. Non-memory variables: - -| Variable | Default | Description | -|----------|---------|-------------| -| `AI_PROVIDER_BASE_URL` | — (required) | AI provider API URL | -| `AI_PROVIDER_API_KEY` | — (required) | AI provider API key | -| `OPENCODE_SERVER_PASSWORD` | — (required) | opencode server password | -| `GITHUB_TOKEN` | — (required) | GitHub personal access token | -| `CONTEXT7_API_KEY` | — (optional) | Context7 MCP API key | -| `ANTIDETECT_BROWSER_MCP_URL` | `http://localhost:8765/mcp` | Antidetect browser MCP URL (optional) | - -Memory variables — see [Memory setup → Environment variables](#environment-variables-1) section. - -### Memory setup - -Plugin `@mathew-cf/opencode-memory` — hybrid search: ripgrep (keyword) + cloud embeddings (OpenRouter Qwen3 8B, 4096 dim, $0.01/M tokens). - -#### How it works - -``` -opencode (plugin) → rag.js wrapper → python3 -m src.memory → OpenRouter API - ↘ ripgrep (keyword search, parallel) -``` - -`memory_search` runs both paths in parallel, merges by score. `memory_save` commits + auto-pushes + incremental reindex (~1 sec). First full reindex: ~4 min for 78 files. - -#### Prerequisites - -1. Fork [`slaid098/opencode-memory`](https://github.com/slaid098/opencode-memory) to your GitHub -2. OpenRouter API key ([openrouter.ai](https://openrouter.ai), Qwen3 8B = $0.01/M tokens) -3. Fill `.env` (see Configuration + Environment variables below) - -#### Initialize - -Docker (recommended): `docker compose up -d` — auto-init via `memory-setup` tool. -Re-run manually: - -```bash -docker exec opencode /root/.config/opencode/scripts/setup-memory.sh -``` - -Bare metal: `uv sync && .opencode/scripts/setup-memory.sh`. - -#### setup-memory.sh steps - -Script is idempotent — safe to re-run: - -1. Create `OPENCODE_MEMORY_DIR` if missing -2. Clone memory repo (or `pull --ff-only` if exists) -3. Verify remote origin matches `OPENCODE_MEMORY_REMOTE` -4. Install post-commit hook (auto-push on `memory_save`) -5. Build RAG index if `.rag/index.json` missing (full reindex, ~4 min) -6. Generate JS wrapper at `rag.js` (delegates to Python CLI; original backed up to `.orig`) - -#### Verify - -```bash -cat node_modules/@mathew-cf/rag-cli/bin/rag.js # Python shim ~10 lines, not Rust binary (71) -cat $OPENCODE_MEMORY_DIR/.rag/meta.json | python3 -m json.tool | head -5 # version + sha256 -ls -la $OPENCODE_MEMORY_DIR/.rag/ # index.json + meta.json + .lock (no index.bin) -``` - -```bash -node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind mount" \ - -i $OPENCODE_MEMORY_DIR/.rag -k 3 --json -``` - -#### Troubleshooting - -| Symptom | Cause | Fix | -|---------|-------|-----| -| `Semantic search is unavailable` | Wrapper not generated / rag-cli not installed | Re-run `setup-memory.sh` | -| Results without scores | Rust rag-cli (old wrapper) | Check `rag.js` is Python shim; re-run `setup-memory.sh` | -| `Index version mismatch` on every run | meta.json missing/stale | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run | -| `OPENAI_BASE_URL env var not set` | `.env` not loaded | Docker: `docker compose up -d --force-recreate`; bare: `.env` in CWD | -| 429 rate limit from OpenRouter | Batch too large / too fast | Reduce `OPENAI_EMBEDDING_BATCH_SIZE` (default 50, max 100) | -| Stale Rust artifacts (`index.bin`) | Migrating from old rag-cli | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run `setup-memory.sh` | - -#### Environment variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `OPENCODE_MEMORY_DIR` | `/root/.local/share/opencode/opencode-memory` | Memory repo location | -| `OPENCODE_MEMORY_REMOTE` | — (required) | Git remote for your opencode-memory fork | -| `OPENAI_BASE_URL` | — (required) | Embeddings API URL (OpenRouter: `https://openrouter.ai/api/v1`) | -| `OPENAI_API_KEY` | — (required) | OpenRouter API key | -| `OPENAI_EMBEDDING_MODEL` | `qwen/qwen3-embedding-8b` | Embedding model (4096 dim) | -| `OPENAI_EMBEDDING_BATCH_SIZE` | `50` | Chunks per API call (OpenRouter max 100) | -| `MEMORY_CHUNK_SIZE` | `512` | Chunk size in characters | -| `MEMORY_CHUNK_OVERLAP` | `64` | Overlap between chunks | -| `MEMORY_WRAPPER_PATH` | (auto) | Override rag.js wrapper path (for tests) | -| `MEMORY_WRAPPER_PYTHON` | (auto) | Override Python binary for wrapper (for tests) | +Copy `.env.example` → `.env`, fill in keys. ## License -MIT — see [LICENSE](LICENSE). \ No newline at end of file +MIT — see [LICENSE](LICENSE). diff --git a/docs/decisions/041-pr-93-readme-minimal-bilingual.md b/docs/decisions/041-pr-93-readme-minimal-bilingual.md new file mode 100644 index 0000000..d30ce43 --- /dev/null +++ b/docs/decisions/041-pr-93-readme-minimal-bilingual.md @@ -0,0 +1,19 @@ +# ADR-041: README minimal bilingual rewrite without memory setup (PR #93) + +## Статус + +Accepted (2026-07-26) + +## Контекст + +PR #89 (предыдущая версия) имел смешение языков (русские секции с английскими заголовками `### Quick start`, `### Configuration`) и был перегружен Memory setup деталями (~100 строк). Пользователь указал на недопустимость смешения языков внутри секций. Memory модуль переписывается — setup детали пока неактуальны. + +## Решение + +Кардинальная переработка — ~55 строк (было 247). Bilingual: `## Русский` (полностью русский, заголовки тоже) + `## English` (полностью английский). Memory setup убран полностью. Configuration = 1 строка (`.env.example` → `.env`). Structure таблица 8 строк (с `.opencode/agents/`, `.opencode/skills/`, `.opencode/scripts/` подсекциями). + +## Альтернативы + +- **Перевести заголовки в русской секции но оставить Memory setup** — отклонено: модуль переписывается, детали не нужны. +- **Оставить английские заголовки в русской секции** — отклонено: пользователь явно указал на недопустимость смешения. +- **Убрать bilingual, оставить только русский** — отклонено: пользователь хочет bilingual для international visitors. diff --git a/docs/handoff/pr-93-readme-minimal-bilingual.md b/docs/handoff/pr-93-readme-minimal-bilingual.md new file mode 100644 index 0000000..87701b5 --- /dev/null +++ b/docs/handoff/pr-93-readme-minimal-bilingual.md @@ -0,0 +1,20 @@ +--- +pr: 93 +title: docs(readme): rewrite to minimal bilingual without memory setup +--- + +## Что сделано + +README переписан в минималистичном bilingual стиле (~55 строк, было 247). Russian primary (`## Русский`, заголовки `### Быстрый старт`, `### Структура`, `### Конфигурация`) + English (`## English`, заголовки `### Quick start`, `### Structure`, `### Configuration`). Memory setup секция убрана полностью (модуль переписывается). Детальные Configuration/Troubleshooting/Environment variables таблицы убраны (`.env.example` = источник правды). + +## Почему + +Предыдущая версия (PR #89) имела смешение языков внутри секций (русские секции с английскими заголовками `### Quick start`, `### Configuration`) и была перегружена Memory setup деталями (~100 строк). Пользователь указал на недопустимость смешения языков внутри секций. Memory модуль переписывается — setup детали пока неактуальны. + +## Pending + +— + +## Watch out + +Memory setup секция убрана — если пользователь захочет вернуть, нужно будет добавить после переписывания memory модуля. .env.example остаётся источником правды для всех env vars.