VS Code — единый сетап для всех проектов Alatyr¶

Задача 33. Готовый runbook: 30-40 минут установки, всё автономно.

Статус: выполнено и проверено 25.08.2026 на Windows. Настроены VS Code, Git, три локальных репозитория, общий workspace, расширения, Foam, Git Graph, Code Spell Checker и Remote SSH к обоим серверам.

Что решаем¶

Один VS Code с одним набором расширений и настроек для:

KB-проектов: alatyr-infra-kb, будущий personal-notes (markdown, wiki-ссылки, RAG-синк)
Кодовых проектов: alatyr-service (Node.js/TS), alatyr-taverna (React/Vite)
Скриптов и конфигов: docker-compose, nginx, YAML, shell

Смотри также knowledge-base-decision.md — почему именно этот путь.

Установка (Windows 10/11)¶

1. Сам VS Code¶

Скачать: https://code.visualstudio.com/download → Windows 64-bit User Installer.

При установке отметить галки: - ✅ Add "Open with Code" action to Windows Explorer file context menu - ✅ Add "Open with Code" action to Windows Explorer directory context menu - ✅ Register Code as an editor for supported file types - ✅ Add to PATH

Проверка после установки в PowerShell:

code --version
git --version

2. Git для Windows (если ещё нет)¶

Скачать: https://git-scm.com/download/win. При установке: - Default editor → Use Visual Studio Code as Git's default editor - Adjusting PATH → Git from the command line and also from 3^rd-party software - HTTPS transport → OpenSSL library - Line endings → Checkout Windows-style, commit Unix-style (важно для наших docker-контейнеров)

3. Клонировать репозитории¶

Создать одну папку для всех репо, например C:\repos\alatyr\:

mkdir C:\repos\alatyr
cd C:\repos\alatyr
git clone git@github.com:oswold1979/alatyr-infra-kb.git
git clone git@github.com:oswold1979/alatyr-service.git
git clone git@github.com:oswold1979/alatyr-taverna.git

Если SSH-ключа для GitHub нет — сначала настроить (см. github-audit.md).

Расширения (устанавливаются одной командой)¶

Открой VS Code → Ctrl+Shift+P → Extensions: Install Extensions — или из терминала:

code --install-extension foam.foam-vscode
code --install-extension yzhang.markdown-all-in-one
code --install-extension davidanson.vscode-markdownlint
code --install-extension bierner.markdown-mermaid
code --install-extension eamodio.gitlens
code --install-extension mhutchie.git-graph
code --install-extension donjayamanne.githistory
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension redhat.vscode-yaml
code --install-extension ms-azuretools.vscode-docker
code --install-extension ms-vscode-remote.remote-ssh
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension mikestead.dotenv
code --install-extension gruntfuggly.todo-tree
code --install-extension streetsidesoftware.code-spell-checker
code --install-extension streetsidesoftware.code-spell-checker-russian
code --install-extension mushan.vscode-paste-image
code --install-extension pkief.material-icon-theme

Что каждое расширение даёт¶

Markdown / wiki-workflow (это ядро):

Foam (foam.foam-vscode) — [[wikilinks]], graph-view, backlinks, tags, автосоздание файлов. Свежий (обновляется активно, 16k+ звёзд). Основа wiki-workflow.
Markdown All in One (yzhang.markdown-all-in-one) — форматирование, TOC, автопродолжение списков, keyboard shortcuts (Ctrl+B — bold, Ctrl+I — italic и т.п.)
markdownlint (davidanson.vscode-markdownlint) — линтер, ловит битую разметку
Markdown Preview Mermaid Support (bierner.markdown-mermaid) — диаграммы в preview

Git:

GitLens (eamodio.gitlens) — blame inline, история строки, сравнение коммитов, поиск по истории
Git Graph (mhutchie.git-graph) — визуальный граф веток и коммитов
Git History (donjayamanne.githistory) — история файла и сравнение версий

Код (для alatyr-service, alatyr-taverna):

Prettier — форматирование JS/TS/JSON/CSS
ESLint — линтер JS/TS
YAML (Red Hat) — schema-валидация docker-compose и GitHub Actions
Docker — inline подсветка Dockerfile, docker-compose, интеграция с Docker Desktop

Скрипты и удалёнка:

Remote SSH — редактирование файлов на VPS/ragserver прямо из VS Code
Python + Pylance — для тебя (advanced) — Python-скрипты, автодополнение, тайпчек
DotENV — подсветка .env файлов

Продуктивность:

Todo Tree — собирает все TODO: и FIXME: из кода в отдельную панель
Code Spell Checker + Russian — орфография в markdown на русском и английском
Paste Image — Ctrl+Alt+V вставляет картинку из буфера в img/ и создаёт markdown-ссылку

Внешний вид:

Material Icon Theme — читаемые иконки в дереве файлов

Настройки¶

Два уровня:

Глобальные (settings.json пользователя) — общие правила для всех проектов
Workspace (в alatyr.code-workspace) — специфичные для наших репо

Глобальные настройки¶

Открой: Ctrl+Shift+P → Preferences: Open User Settings (JSON).

Файл настроек с готовым содержимым в этом же репо: skeletons/vscode-user-settings.json. Скопируй в свой settings.json или объедини с существующими настройками. Перед заменой существующего файла сделай timestamp-копию; файл может содержать локальные настройки расширений.

Workspace-файл¶

В корне C:\repos\alatyr\ сохранить файл alatyr.code-workspace. Готовый файл: skeletons/alatyr.code-workspace — скопируй его и открывай через File → Open Workspace from File.

Плюсы workspace-файла: - Все 3 репо в одном окне VS Code (переключение Ctrl+P без открытия отдельных окон) - Foam видит все markdown-файлы всех проектов и умеет [[wikilinks]] между репо - Git-панель показывает статус всех репо одновременно - Общий поиск (Ctrl+Shift+F) по всем проектам сразу

Работа с wiki-ссылками (Foam)¶

Синтаксис (совместим с Obsidian и Open WebUI)¶

[[имя-файла]]              → ссылка на файл в текущем workspace
[[имя-файла|отображаемый]] → ссылка с подписью
[[имя-файла#заголовок]]    → ссылка на секцию
![[имя-файла]]             → embed (вставка содержимого)
![[картинка.png]]          → embed картинки

Функции Foam:¶

Ctrl+Click по [[имя-файла]] — переход
Автодополнение — начни печатать [[ и увидишь список файлов
Backlinks panel — Explorer sidebar → "Backlinks", показывает откуда ссылаются на текущий файл
Graph view — Ctrl+Shift+P → Foam: Show Graph
Rename symbol (F2) — переименование файла обновляет все [[wikilinks]] в workspace

Совместимость с Open WebUI¶

Open WebUI понимает [[wikilinks]] как обычный текст (не резолвит в ссылки), но RAG-поиск всё равно находит связанные документы семантически. Так что [[имя-файла]] работает и как навигационная ссылка в VS Code, и как семантический якорь в RAG.

Git-workflow¶

Правила коммитов (из инструкций проекта)¶

git -c user.email="oswold1979@gmail.com" -c user.name="Roman Golovin" commit -m "..."

Или настроить один раз глобально:

git config --global user.email "oswold1979@gmail.com"
git config --global user.name "Roman Golovin"

Через GitLens (визуальный git)¶

Blame inline — курсор на строке, справа появляется автор и дата последнего изменения
View History — правый клик по файлу → "Open File History"
Compare with previous — Ctrl+Shift+P → Git: Compare with Previous Commit

Через Git Graph¶

Ctrl+Shift+P → Git Graph: View Git Graph — визуальный граф всех веток. Правый клик по коммиту → cherry-pick, revert, reset и т.п.

Auto-fetch (авто-подтягивание изменений с GitHub)¶

В глобальных настройках уже включён git.autofetch: true (см. vscode-user-settings.json). Раз в 3 минуты VS Code делает git fetch — ты сразу видишь если на GitHub есть новые коммиты (стрелочка вниз в статус-баре).

Auto-commit не включаем — коммитим осмысленно, каждый коммит с message.

RAG-синхронизация (автоматика)¶

Пишешь → коммитишь → пушишь на GitHub. Дальше без твоего участия:

Ragserver раз в 10 минут делает git pull в /opt/rag-kb/alatyr-infra-kb/
sync-to-openwebui.sh (cron */10) обнаруживает изменения и заливает в Open WebUI
Open WebUI переиндексирует, обновляет векторы в Qdrant
После ближайшего 10-минутного цикла синхронизации изменения становятся доступны в RAG

Проверить синк — https://rag.alatyr-service.ru → Workspace → Knowledge → alatyr-infra-kb.

Подробнее: rag-sync.md.

Работа с VPS/ragserver через VS Code (Remote SSH)¶

Позволяет редактировать файлы прямо на сервере — тот же UI, но файлы удалённые.

Настройка¶

Ctrl+Shift+P → Remote-SSH: Open SSH Configuration File → выбрать %USERPROFILE%\.ssh\config
Добавить блоки:

Host vps-hostkey
    HostName 46.17.99.183
    User root
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    Port 22

Host ragserver
    HostName 192.168.1.200
    User oswold
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    Port 22

Ctrl+Shift+P → Remote-SSH: Connect to Host → выбрать vps-hostkey или ragserver

Ragserver доступен только из LAN или через AmneziaWG VPN — если ты не дома, подключай VPN перед SSH.

На 25.08.2026 отдельного пользователя oswold на VPS нет, поэтому профиль vps-hostkey использует root. Это текущее рабочее состояние, а не целевая модель безопасности: отдельного администратора с sudo и запрет прямого парольного входа root следует вынести в задачу hardening.

Если подключение к VPS зависает по timeout при работающем sshd и разрешённом UFW 22/tcp, проверь jail sshd в Fail2ban. Во время первичной настройки домашний IP 176.99.153.164 был заблокирован и потребовал точечного unbanip; постоянный whitelist не добавлялся.

Внимание: для production-правок VPS ходим через SSH-терминал (bash), а не через VS Code Remote — Remote SSH удобен для просмотра логов и правки конфигов, но нежелателен для критических операций.

Расширение на другие проекты (единый принцип)¶

Для alatyr-service (документация)¶

Создать папку docs/ в репо:

alatyr-service/
├── src/
├── docs/                    ← новая
│   ├── README.md
│   ├── api-endpoints.md
│   └── deployment.md
├── docker-compose.yml
└── ...

Добавить в sync-to-openwebui.sh (задача — расширить скрипт):

# --- новый источник ---
REPO_SERVICE=/opt/rag-kb/alatyr-service/docs
COLLECTION_SERVICE="alatyr-service-docs"
# логика синка docs/ в отдельную collection

Для alatyr-taverna и будущих проектов¶

Аналогично: папка docs/ в репо → collection в Open WebUI.

Для personal-notes (личные заметки)¶

Отдельный приватный репо github.com/oswold1979/personal-notes. Синкать в collection personal (доступ только у Романа в Open WebUI через настройку permissions).

Что делать после установки (checklist)¶

Что мы НЕ ставим (и почему)¶

Obsidian Git — Obsidian вообще не используем (решение)
Continue.dev / Cursor / Copilot — отдельная задача 34, оцениваем позже
Live Server — для alatyr-taverna используем npm run dev (Vite)
Auto-commit плагины — коммитим руками с осмысленными message
Тяжёлые темы оформления — Material Icon Theme даёт иконки, тема оставляем VS Code Dark+ (родная)

Известные особенности¶

Foam vs Markdown Memo¶

Оба поддерживают [[wikilinks]]. Foam активнее развивается и имеет graph-view, но в markdown-preview VS Code ссылки не всегда кликабельны (нужен Foam extension). Markdown Memo делает то же с чуть лучшей preview-совместимостью, но менее активен. Ставим Foam как основной.

Русский язык в spell-check¶

Code Spell Checker + Russian dictionary работают вместе. Игнор-словарь проекта хранится в .cspell.json — можно добавлять свои термины (Alatyr, Vaultwarden, AmneziaWG, ragserver и т.п.). Файл .cspell.json — уже в репо alatyr-infra-kb (если нет, добавим).

Line endings¶

Windows использует CRLF, Linux — LF. У нас все скрипты и docker-конфиги — LF. Настройка "files.eol": "\n" в глобальных настройках заставит VS Code сохранять новые файлы с LF. Для существующих файлов git автоматически конвертирует по правилу из установки Git (checkout Windows, commit Unix).

Связанные документы¶

knowledge-base-decision.md — решение по единой базе (задача 33 контекст)
openwebui-public-api.md — API для внешних клиентов (задача 36)
rag-sync.md — механика синхронизации git → Open WebUI
github-audit.md — GitHub-репозитории и SSH-настройка
dev-workflow.md — общий workflow разработки

Готовые артефакты в этом репо¶

skeletons/vscode-user-settings.json — глобальные настройки VS Code
skeletons/alatyr.code-workspace — workspace-файл для мульти-репо
skeletons/vscode-extensions.txt — список расширений (для быстрой переустановки)
skeletons/vscode-cspell.json — словарь исключений для spell-checker