From d8768a16424f544513c0316d22416e19449a0ea2 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sun, 22 Mar 2026 17:32:42 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BF=D0=B8?= =?UTF-8?q?=D1=81=D0=B0=D0=BD=20README=20=D0=BF=D0=BE=20=D0=BF=D1=80=D0=B8?= =?UTF-8?q?=D0=BD=D1=86=D0=B8=D0=BF=D1=83=20=C2=AB=D0=BF=D0=BB=D0=B0=D1=82?= =?UTF-8?q?=D1=84=D0=BE=D1=80=D0=BC=D0=B0=20=E2=86=92=20=D0=B4=D0=B5=D0=B9?= =?UTF-8?q?=D1=81=D1=82=D0=B2=D0=B8=D0=B5=20=E2=86=92=20=D1=81=D0=BF=D1=80?= =?UTF-8?q?=D0=B0=D0=B2=D0=BE=D1=87=D0=BD=D0=B8=D0=BA=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - README вырос органически и перестал соответствовать тому, как человек его читает: quick start был на строке 80, требования после инструкций, Windows-справочник внутри установки, прокси и секреты размазаны по 4 местам. - Что: - добавлен quick start наверху (3 команды для каждой платформы). - содержимое сгруппировано по платформе: Linux/WSL (stow), Windows (chezmoi), AI-инструменты. - прокси, секреты и Git baseline консолидированы в отдельные секции. - добавлены секции «Справочник» (bash/pwsh функции, точки расширения) и «Дизайн-решения». - удалены дубли и заглушки (Stow вручную, Zed placeholder, VS Code Server как отдельная секция). - Проверка: - визуальный просмотр README.md. - git diff --check — нет trailing whitespace / CRLF. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 349 +++++++++++++++++++++--------------------------------- 1 file changed, 137 insertions(+), 212 deletions(-) diff --git a/README.md b/README.md index 2d5c9d7..eaece36 100644 --- a/README.md +++ b/README.md @@ -1,236 +1,109 @@ # Dotfiles -Персональные конфигурационные файлы для настройки рабочего окружения. +Персональные конфигурации для Linux/WSL (stow) и Windows (chezmoi). -## 📦 Содержимое +## 🚀 Quick start -### Bash -- **Файлы:** `bash/.bash_custom`, `bash/.bash_functions`, `bash/.bash_prompt` -- Подключение кастомных bash-файлов (функции, prompt, секреты) поверх стандартного `~/.bashrc` -- Кастомный двухстрочный prompt (подключается из `~/.bash_prompt`) -- Поддержка цветного вывода и автодополнения - -### Tmux -- **Файл:** `tmux/.tmux.conf` -- Два префикса: `Ctrl+b` (стандартный) и `Ctrl+Space` (удобный) -- Визуальный стиль с синей цветовой схемой -- Vi-режим для копирования -- Горячие клавиши: - - `|` / `-` — разделение панелей - - `Alt+стрелки` — изменение размера панелей и переключение окон - - `r` — перезагрузка конфига - -### Vim -- **Файл:** `vim/.vimrc` -- Минималистичная конфигурация без плагинов -- 2 пробела вместо табов (оптимально для YAML/XML) -- Поддержка мыши и подсветка поиска -- Leader key: `Space` - - `w` — сохранить - - `h` — убрать подсветку поиска - - `p` — вставка без форматирования - -### Zed -- **Директория:** `zed/.config/zed/` -- Структура для конфигурации Zed редактора - -### VS Code (WSL) -- **Файл:** `vscode/.vscode-server/server-env-setup` -- Поддержка `~/.vscode-server/server-env-setup` для VS Code Server в WSL -- Подгрузка `~/.env.secrets` для расширений, задач/debug и терминалов VS Code -- Автоматическая настройка прокси: если `hproxy.local` резолвится, выставляются `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (socks5), `NO_PROXY` и их lowercase-варианты -- Режим `fail-open`: если `~/.env.secrets` отсутствует или не загружается — warning в stderr, VS Code продолжает запуск - -### Opencode -- **Директория:** `opencode/.config/opencode/` -- Конфигурация AI-ассистента opencode с MCP-серверами: - - **context7** — документация библиотек - - **web-reader** — чтение веб-страниц - - **web-search-prime** — поиск в интернете - - **zread** — чтение GitHub репозиториев - - **playwright** — браузерная автоматизация -- Требует переменных окружения (см. `.env.example`) -- Скиллы берутся из общего пакета `agents/.agents/skills/` через симлинк `~/.config/opencode/skills` - -### Agents (shared skills) -- **Директория:** `agents/.agents/skills/` -- Каноничное место для общих скиллов в формате `~/.agents/skills//SKILL.md` - -### Codex -- **Директория:** `codex/.codex/skills/` -- Тонкие симлинки в `~/.codex/skills/` на общие skills из `~/.agents/skills/` - -### Claude -- **Директория:** `claude/.claude/` -- Тонкий симлинк `~/.claude/skills` на общие skills из `~/.agents/skills/` -- **Двухуровневые настройки:** - - `settings.json` (в dotfiles, read-only) — стабильная база: permissions, statusLine - - `settings.local.json` (локальный, не в git) — машинно-специфичное: model, effortLevel -- Claude Code мержит оба файла, `settings.local.json` имеет приоритет -- `settings.json` защищён `chmod 444`, чтобы Claude Code не перезаписывал tracked файл - -### Gemini -- **Директория:** `gemini/.gemini/` -- Политики для Gemini CLI: pre-approved readonly команды - -## 🚀 Установка - -### Автоматическая (рекомендуется) +### Linux / WSL ```bash -sudo apt install stow git clone https://github.com/ddmitry/dotfiles ~/dotfiles cd ~/dotfiles ./install.sh ``` -Скрипт `install.sh`: -- Применяет все stow пакеты -- Создаёт `~/.claude/settings.local.json` с дефолтными model/effortLevel -- Защищает `settings.json` от перезаписи (`chmod 444`) -- Автоматически добавляет подключение bash_custom в `~/.bashrc` -- В WSL предлагает настроить автоматический резолв `hproxy.local` (см. ниже) +`install.sh` применяет stow-пакеты, настраивает Claude/Opencode, подключает `~/.bash_custom` в `~/.bashrc` и в WSL предлагает настроить `hproxy.local`. -### Stow вручную - -```bash -sudo apt install stow -cd /path/to/dotfiles -stow bash tmux vim zed vscode agents opencode codex claude gemini -``` - -После stow добавьте в `~/.bashrc` (если не используете `install.sh`): -```bash -[ -f ~/.bash_custom ] && source ~/.bash_custom -``` - -Создайте локальные настройки Claude: -```bash -cat > ~/.claude/settings.local.json <<'EOF' -{ - "model": "opus", - "effortLevel": "high" -} -EOF -``` - -### Windows (chezmoi) - -Для Windows предпочтителен отдельный source dir `chezmoi/` внутри этого репозитория. Это позволяет держать Windows-слой рядом с остальными dotfiles, не ломая существующий `stow`/`install.sh` workflow для Linux/WSL. - -> 💡 **Примечание:** chezmoi также работает на Linux/WSL, но stow предпочтительнее для полной функциональности. - -**⚠️ Требования:** -- Developer Mode должен быть включён (для создания симлинков) - > Settings → System → For developers → Developer Mode → On -- `pwsh` 7.x для повседневной работы -- `Windows PowerShell 5.1` остаётся legacy-режимом и не тюнится агрессивно - -**Быстрое применение из уже существующего `~/dotfiles`:** +### Windows ```powershell winget install --id Microsoft.PowerShell winget install twpayne.chezmoi - -# Применить только Windows-layer из репозитория chezmoi -S "$HOME\dotfiles\chezmoi" apply ``` -Этот режим не требует менять глобальный source `chezmoi`: достаточно запускать `chezmoi -S "$HOME\dotfiles\chezmoi" apply` из уже существующего репозитория. - -Windows-слой в этом репозитории настраивает современный `PowerShell 7` как основной рабочий shell. `Windows PowerShell 5.1` сознательно остаётся legacy-режимом совместимости и не получает новые helper-функции, форсированный UTF-8 или другие агрессивные изменения без отдельного явного запроса. - -**Что делает текущий Windows-layer:** -- ✅ ставит маленький live-stub в `~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1` -- ✅ хранит основную логику `pwsh` в `~/.config/powershell/profile.ps1` -- ✅ хранит Git baseline в `~/.gitconfig`, а локальные overrides в `~/.gitconfig.local` -- ✅ оставляет hook'и для локальных добавок: `~/.config/powershell/profile.extra.ps1` и `~/.config/powershell/profile.d/*.ps1` -- ✅ идемпотентно приводит `Windows Terminal` к базовому состоянию без полной перезаписи всего `settings.json` - -**Какие helper-функции есть в `pwsh`:** -- `Reload-Profile` — перечитывает текущий профиль без перезапуска сессии -- `which` — показывает все найденные команды по имени через `Get-Command -All` -- `touch` — создаёт файл или обновляет `LastWriteTime` -- `mkcd` — создаёт директорию и сразу переходит в неё -- `open` — открывает путь через `Invoke-Item` -- `croot` — переходит в корень текущего Git-репозитория -- `proxy_on` — включает `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` для `hproxy.local:12334` -- `proxy_off` — очищает proxy-переменные текущей сессии -- `myip` — быстро показывает текущий внешний IP -- `wt-here` — открывает новое окно Windows Terminal в текущей директории -- `wt-tab-here` — открывает новую вкладку Windows Terminal в текущей директории -- `wt-split-here` — открывает split-pane Windows Terminal в текущей директории - -**Что сознательно не делается:** -- ❌ `Windows PowerShell 5.1` не форсируется в UTF-8 и не меняется без явного запроса -- ❌ Linux/WSL-поток не переносится в chezmoi и продолжает жить через `stow`/`install.sh` - -**Что фиксирует Git baseline для Windows:** -- `core.autocrlf = false` -- `core.eol = lf` -- `core.quotepath = false` -- `core.longpaths = true` -- `fetch.prune = true` -- `pull.ff = only` -- `init.defaultBranch = main` -- `user.name`, `user.email`, `core.editor` и `core.sshCommand` в baseline не входят и должны жить в `~/.gitconfig.local` -- Проверять итоговые значения удобнее через `git config --global --includes --list --show-origin` +Chezmoi использует отдельный source dir `chezmoi/` внутри этого репозитория, не трогая stow/install.sh workflow. ## 🔧 Требования -### Linux/WSL -- Linux (протестировано на Ubuntu) -- Bash 4.0+ -- Tmux 2.0+ -- Vim 8.0+ +### Linux / WSL + +- Ubuntu / Debian +- GNU stow +- Bash 4.0+, Tmux 2.0+, Vim 8.0+ ### Windows -- Windows 10/11 с Developer Mode + +- Windows 10/11 + Developer Mode (Settings → System → For developers) - PowerShell 7.x - [chezmoi](https://www.chezmoi.io/) -## 📝 Дополнительные файлы +> `Windows PowerShell 5.1` остаётся legacy-режимом совместимости — не форсируется в UTF-8 и не тюнится. -Для полной настройки создайте: -- `~/.bash_aliases` — персональные алиасы -- `~/.env.secrets` — приватные переменные окружения (API ключи) +## 📦 Что включено -## 🔑 Переменные окружения +### Linux / WSL (stow) -### Кастомные функции bash +| Пакет | Что делает | +|-------|------------| +| `bash` | Кастомный prompt, функции (`proxy_on/off`, `myip`), подгрузка секретов | +| `tmux` | Два префикса (`Ctrl+b`, `Ctrl+Space`), vi-режим, split по `\|` / `-` | +| `vim` | Минимальный .vimrc без плагинов, 2 пробела, leader = `Space` | +| `zed` | Конфигурация Zed редактора | +| `vscode` | `server-env-setup` для VS Code Server в WSL: секреты + авто-прокси | -Файл `bash/.bash_functions` содержит пользовательские функции (proxy_on/off, myip и др.). -При использовании `stow bash` он будет доступен как `~/.bash_functions`. +`install.sh` дополнительно настраивает opencode (симлинки, MCP-конфиг), claude (копирует `settings.json` с `chmod 444`, создаёт `settings.local.json`) и подключает bash_custom. -### Приватные переменные (секреты) +### Windows (chezmoi) + +- **PowerShell 7 profile** — live-stub в `~/Documents/PowerShell/` загружает managed profile из `~/.config/powershell/profile.ps1` +- **Git baseline** — `~/.gitconfig` с managed настройками, `~/.gitconfig.local` для персональных overrides +- **Windows Terminal** — идемпотентный скрипт: PS7 по умолчанию, PS 5.1 как legacy, Azure Cloud Shell скрыт +- **UTF-8** — `chcp 65001` + `Console.InputEncoding/OutputEncoding` только для pwsh 7, не для PS 5.1 +- **Extension points** — `~/.config/powershell/profile.extra.ps1` и `profile.d/*.ps1` для локальных добавок + +### AI-инструменты (кросс-платформа) + +Общие скиллы живут в `agents/.agents/skills/` и расшариваются через симлинки. + +| Инструмент | Что настраивается | +|------------|-------------------| +| **Agents** | Каноничное хранилище скиллов: `~/.agents/skills//SKILL.md` | +| **Claude** | `~/.claude/skills` → симлинк на agents; `settings.json` (read-only) + `settings.local.json` (локальный) | +| **Opencode** | MCP-серверы (context7, web-reader, playwright и др.), `~/.config/opencode/skills` → симлинк на agents | +| **Codex** | `~/.codex/skills/` → симлинки на agents | +| **Gemini** | Политики для CLI: pre-approved readonly команды | + +## ⚙️ Настройка + +### Секреты (`.env.secrets`) -1. Скопируйте шаблон: ```bash cp bash/.env.secrets.example ~/.env.secrets ``` -2. Отредактируйте и добавьте API ключи: -```bash -# Context7 API (https://context7.com) -export CONTEXT7_API_KEY="your_context7_api_key_here" +Содержимое — API-ключи для AI-инструментов: -# Z.AI API для LLM, поиска и чтения (https://z.ai) -export ZAI_API_KEY="your_zai_api_key_here" +```bash +export CONTEXT7_API_KEY="..." # https://context7.com +export ZAI_API_KEY="..." # https://z.ai ``` -Файл `~/.env.secrets` автоматически подгружается при старте shell. +Файл подгружается при старте bash и VS Code Server. Не трекается в git. -### WSL: настройка hproxy.local +### Прокси (`hproxy.local`) -Имя `hproxy.local` используется как алиас для хоста, на котором работает прокси-сервер. Это позволяет функциям `proxy_on`/`proxy_off` и VS Code Server не зависеть от конкретного IP-адреса. +Имя `hproxy.local` — алиас хоста с прокси. Все инструменты (bash, pwsh, VS Code Server) используют его для `proxy_on/off`, не завязываясь на конкретный IP. -**NAT mode** (по умолчанию в WSL2) — IP шлюза меняется при каждом запуске, поэтому нужен автоматический boot-скрипт: +**Порты:** HTTP/HTTPS — `hproxy.local:12334`, SOCKS5 — `socks5://hproxy.local:12334`. + +**WSL NAT mode** (IP шлюза меняется при каждом запуске): ```bash -# Вариант 1: через install.sh (интерактивно) -./install.sh # ответьте "y" на вопрос про wsl.conf +# Через install.sh (интерактивно, ответить "y" на вопрос про wsl.conf) +./install.sh -# Вариант 2: вручную +# Или вручную: sudo tee -a /etc/wsl.conf <<'EOF' [boot] @@ -238,41 +111,93 @@ command = "/path/to/dotfiles/scripts/setup-hproxy.sh" EOF ``` -После изменения `wsl.conf` перезапустите WSL: `wsl --shutdown`. +После изменения `wsl.conf` — `wsl --shutdown`. Обновить без перезапуска: `sudo scripts/setup-hproxy.sh` или `update_hproxy`. -Обновить `hproxy.local` без перезапуска WSL: -```bash -sudo scripts/setup-hproxy.sh -# или -update_hproxy # интерактивная функция из .bash_functions -``` - -**Mirror mode** (`networkingMode=mirrored` в `.wslconfig`) — WSL разделяет сетевой стек с хостом, IP не меняется. Достаточно один раз прописать запись в Windows hosts: +**WSL Mirror mode** (`networkingMode=mirrored`) — IP не меняется, достаточно одной записи: ``` # C:\Windows\System32\drivers\etc\hosts 192.168.1.100 hproxy.local ``` -### VS Code Server в WSL +**VS Code Server** — `vscode/.vscode-server/server-env-setup` автоматически подхватывает `hproxy.local` и выставляет все proxy-переменные (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY и lowercase-варианты). Если `hproxy.local` не резолвится — прокси не включается, запуск не блокируется. -Файл `vscode/.vscode-server/server-env-setup` выполняется при каждом старте VS Code Server в WSL и делает две вещи: +**Windows pwsh** — `proxy_on` / `proxy_off` / `myip` работают аналогично bash-версиям. -1. **Загружает `~/.env.secrets`** — API ключи становятся доступны расширениям, задачам и терминалам VS Code. Если файл отсутствует или содержит ошибку, выводится warning в stderr, запуск не блокируется. +### Git baseline -2. **Настраивает прокси** — если `hproxy.local` резолвится (через `/etc/hosts` или DNS в режиме mirror), автоматически выставляются: - - `HTTP_PROXY` / `http_proxy` → `http://hproxy.local:12334` - - `HTTPS_PROXY` / `https_proxy` → `http://hproxy.local:12334` - - `ALL_PROXY` / `all_proxy` → `socks5://hproxy.local:12334` - - `NO_PROXY` / `no_proxy` → `hproxy.local,localhost,127.0.0.1,.concept-software.ru` +На всех платформах фиксируются настройки для предсказуемого поведения: -После установки/обновления файла сделайте одно из действий: -- `Developer: Reload Window` в VS Code -- или `Remote-WSL: Reconnect to WSL` +| Ключ | Значение | Зачем | +|------|----------|-------| +| `core.autocrlf` | `false` | Не переписывать line endings | +| `core.eol` | `lf` | Дефолт ближе к Linux/macOS | +| `core.quotepath` | `false` | Кириллица в путях читаема | +| `core.longpaths` | `true` | Длинные пути на Windows | +| `fetch.prune` | `true` | Убирать удалённые ветки | +| `pull.ff` | `only` | Защита от случайных merge commit | +| `init.defaultBranch` | `main` | — | -Если у вас уже есть локальный `~/.vscode-server/server-env-setup`, stow может сообщить конфликт. -Тогда сохраните старую версию и примените stow повторно: -```bash -mv ~/.vscode-server/server-env-setup ~/.vscode-server/server-env-setup.bak.$(date +%Y%m%d%H%M%S) -stow -vt ~ vscode +Персональные настройки (`user.name`, `user.email`, `core.editor`, `core.sshCommand`) живут в `~/.gitconfig.local`. + +На Windows chezmoi при первом apply мигрирует существующий `~/.gitconfig` в `~/.gitconfig.local` и подставляет managed baseline. На Linux baseline задаётся вручную или через скрипты. + +Проверка: `git config --global --includes --list --show-origin`. + +Для кроссплатформенных репозиториев рекомендуется `.gitattributes`: + +```gitattributes +* text=auto eol=lf +*.bat text eol=crlf +*.cmd text eol=crlf ``` + +## 📖 Справочник + +### Bash-функции (`~/.bash_functions`) + +| Функция | Описание | +|---------|----------| +| `proxy_on` | Включает HTTP/HTTPS/SOCKS5 прокси через `hproxy.local:12334` | +| `proxy_off` | Очищает proxy-переменные | +| `myip` | Показывает текущий внешний IP | +| `update_hproxy` | Обновляет `hproxy.local` в `/etc/hosts` (WSL NAT mode) | + +### PowerShell-функции (`~/.config/powershell/profile.ps1`) + +| Функция | Описание | +|---------|----------| +| `proxy_on` | Включает HTTP/HTTPS/SOCKS5 прокси через `hproxy.local:12334` | +| `proxy_off` | Очищает proxy-переменные | +| `myip` | Показывает текущий внешний IP | +| `Reload-Profile` | Перечитывает профиль без перезапуска сессии | +| `which` | `Get-Command -All` по имени | +| `touch` | Создаёт файл или обновляет `LastWriteTime` | +| `mkcd` | Создаёт директорию и переходит в неё | +| `open` | `Invoke-Item` — открывает путь | +| `croot` | Переходит в корень текущего Git-репозитория | +| `wt-here` | Новое окно Windows Terminal в текущей директории | +| `wt-tab-here` | Новая вкладка в текущей директории | +| `wt-split-here` | Split-pane в текущей директории | + +### Точки расширения + +| Файл | Назначение | +|------|------------| +| `~/.env.secrets` | API-ключи, подгружается bash и VS Code Server | +| `~/.bash_aliases` | Персональные алиасы bash | +| `~/.gitconfig.local` | Персональные Git-настройки (`user.name`, `core.editor` и т.д.) | +| `~/.config/powershell/profile.extra.ps1` | Локальные дополнения к pwsh-профилю | +| `~/.config/powershell/profile.d/*.ps1` | Фрагменты, загружаемые по алфавиту | +| `~/.claude/settings.local.json` | Машинно-специфичные настройки Claude Code (`model`, `effortLevel`) | + +## 💡 Дизайн-решения + +**Почему stow на Linux + chezmoi на Windows?** +stow проще и покрывает весь Linux/WSL workflow. chezmoi нужен на Windows, где stow недоступен и нужны run-скрипты (миграция `.gitconfig`, настройка Windows Terminal). Два инструмента живут рядом и не мешают друг другу: chezmoi использует отдельный source dir `chezmoi/`, а `.chezmoiignore` исключает Linux-файлы на Windows. + +**Почему Windows PowerShell 5.1 не трогается?** +Форсирование UTF-8 и изменение профиля PS 5.1 может сломать старые скрипты, `.bat`/`.cmd` и консольные утилиты. PS 7 — основной shell, PS 5.1 — режим совместимости. + +**Почему Claude `settings.json` копируется, а не симлинкается?** +Claude Code перезаписывает `settings.json` при любом изменении настроек. Если файл — симлинк на tracked файл в git, это создаёт нежелательные diff-ы. Копия с `chmod 444` защищает от перезаписи; машинно-специфичные настройки уходят в `settings.local.json`.