slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

docs(readme): rewrite to minimal bilingual without memory setup (#93)

Browse source 
* docs(readme): rewrite to minimal bilingual without memory setup

* docs(handoff): add handoff + ADR for README minimal rewrite

* docs(handoff): set PR number

* fix(docs): translate Structure descriptions to Russian in README

---------

Co-authored-by: opencode-agent <agent@opencode.local>
This commit is contained in:
Sergey 2026-07-26 23:41:41 +03:00 • committed by GitHub
parent 0983327605
commit e6c378410f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 63 additions and 204 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

228
README.md
View file

@ -1,126 +1,36 @@
# opencode-config # 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 ```bash
git clone https://github.com/slaid098/opencode-config.git git clone https://github.com/slaid098/opencode-config.git
cd opencode-config cd opencode-config
cp .env.example .env # заполнить ключи (см. Configuration) cp .env.example .env
docker compose up -d docker compose up -d
``` ```
Доступ: http://localhost:4096. Память инициализируется автоматически при первом старте контейнера. Доступ: http://localhost:4096
### Structure ### Структура
| Путь | Описание | | Путь | Описание |
|------|----------| |------|----------|
| `AGENTS.md` | Глобальные правила оркестратора (главный агент = только план) | | `AGENTS.md` | Глобальные правила оркестратора |
| `.opencode/` | Конфигурация проекта (auto-discovered, без env var) | | `.opencode/` | Конфигурация проекта |
| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) | | `.opencode/agents/` | Определения subagent'ов |
| `.opencode/skills/` | Skill definitions (14 skills) | | `.opencode/skills/` | Определения skills (14 skills) |
| `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) | | `.opencode/scripts/` | Python скрипты (pipeline-status, spec-status) |
| `src/` | Python RAG CLI (memory) | | `src/` | Python RAG CLI |
| `docs/` | Handoffs, ADRs, project map | | `docs/` | Handoffs, ADRs, project map |
| `docker-compose.yml` | Docker compose конфиг |
### Configuration ### Конфигурация
Скопируйте `.env.example` → `.env` и заполните. Не-memory переменные: Скопируйте `.env.example` → `.env`, заполните ключи.
| 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) |
## English ## English
@ -129,119 +39,29 @@ node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind moun
```bash ```bash
git clone https://github.com/slaid098/opencode-config.git git clone https://github.com/slaid098/opencode-config.git
cd opencode-config cd opencode-config
cp .env.example .env # fill in keys (see Configuration) cp .env.example .env
docker compose up -d docker compose up -d
``` ```
Access at http://localhost:4096. Memory initializes automatically on first container start. Access at http://localhost:4096
### Structure ### Structure
| Path | Description | | Path | Description |
|------|-------------| |------|-------------|
| `AGENTS.md` | Global orchestrator rules (main agent = plan only) | | `AGENTS.md` | Global orchestrator rules |
| `.opencode/` | Project-local config (auto-discovered, zero env var) | | `.opencode/` | Project configuration |
| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) | | `.opencode/agents/` | Subagent definitions |
| `.opencode/skills/` | Skill definitions (14 skills) | | `.opencode/skills/` | Skill definitions (14 skills) |
| `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) | | `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) |
| `src/` | Python RAG CLI (memory) | | `src/` | Python RAG CLI |
| `docs/` | Handoffs, ADRs, project map | | `docs/` | Handoffs, ADRs, project map |
| `docker-compose.yml` | Docker compose config |
### Configuration ### Configuration
Copy `.env.example` → `.env` and fill in. Non-memory variables: Copy `.env.example` → `.env`, fill in keys.
| 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) |
## License ## License
MIT — see [LICENSE](LICENSE). MIT — see [LICENSE](LICENSE).

19
docs/decisions/041-pr-93-readme-minimal-bilingual.md Normal file
View file

@ -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.

20
docs/handoff/pr-93-readme-minimal-bilingual.md Normal file
View file

@ -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.