ddmitry/dotfiles
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: переписан README по принципу «платформа → действие → справочник»

Browse Source 
- Зачем:
  - 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) <noreply@anthropic.com>
This commit is contained in:
Dmitry DementievandClaude Opus 4.6 committed 2026-03-22 17:32:42 +03:00
1 parent 4331b0c02c
commit d8768a1642
1 file changed
+137 -212
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+137 -212
View File
@@ -1,236 +1,109 @@
# Dotfiles # Dotfiles
Персональные конфигурационные файлы для настройки рабочего окружения. Персональные конфигурации для Linux/WSL (stow) и Windows (chezmoi).
## 📦 Содержимое ## 🚀 Quick start
### Bash ### Linux / WSL
- **Файлы:** `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`
- `<Space>w` — сохранить
- `<Space>h` — убрать подсветку поиска
- `<Space>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/<name>/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 команды
## 🚀 Установка
### Автоматическая (рекомендуется)
```bash ```bash
sudo apt install stow
git clone https://github.com/ddmitry/dotfiles ~/dotfiles git clone https://github.com/ddmitry/dotfiles ~/dotfiles
cd ~/dotfiles cd ~/dotfiles
./install.sh ./install.sh
``` ```
Скрипт `install.sh`: `install.sh` применяет stow-пакеты, настраивает Claude/Opencode, подключает `~/.bash_custom` в `~/.bashrc` и в WSL предлагает настроить `hproxy.local`.
- Применяет все stow пакеты
- Создаёт `~/.claude/settings.local.json` с дефолтными model/effortLevel
- Защищает `settings.json` от перезаписи (`chmod 444`)
- Автоматически добавляет подключение bash_custom в `~/.bashrc`
- В WSL предлагает настроить автоматический резолв `hproxy.local` (см. ниже)
### Stow вручную ### Windows
```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`:**
```powershell ```powershell
winget install --id Microsoft.PowerShell winget install --id Microsoft.PowerShell
winget install twpayne.chezmoi winget install twpayne.chezmoi
# Применить только Windows-layer из репозитория
chezmoi -S "$HOME\dotfiles\chezmoi" apply chezmoi -S "$HOME\dotfiles\chezmoi" apply
``` ```
Этот режим не требует менять глобальный source `chezmoi`: достаточно запускать `chezmoi -S "$HOME\dotfiles\chezmoi" apply` из уже существующего репозитория. Chezmoi использует отдельный source dir `chezmoi/` внутри этого репозитория, не трогая stow/install.sh workflow.
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`
## 🔧 Требования ## 🔧 Требования
### Linux/WSL ### Linux / WSL
- Linux (протестировано на Ubuntu)
- Bash 4.0+ - Ubuntu / Debian
- Tmux 2.0+ - GNU stow
- Vim 8.0+ - Bash 4.0+, Tmux 2.0+, Vim 8.0+
### Windows ### Windows
- Windows 10/11 с Developer Mode
- Windows 10/11 + Developer Mode (Settings → System → For developers)
- PowerShell 7.x - PowerShell 7.x
- [chezmoi](https://www.chezmoi.io/) - [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 и др.). `install.sh` дополнительно настраивает opencode (симлинки, MCP-конфиг), claude (копирует `settings.json` с `chmod 444`, создаёт `settings.local.json`) и подключает bash_custom.
При использовании `stow bash` он будет доступен как `~/.bash_functions`.
### Приватные переменные (секреты) ### 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/<name>/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 ```bash
cp bash/.env.secrets.example ~/.env.secrets cp bash/.env.secrets.example ~/.env.secrets
``` ```
2. Отредактируйте и добавьте API ключи: Содержимое — API-ключи для AI-инструментов:
```bash
# Context7 API (https://context7.com)
export CONTEXT7_API_KEY="your_context7_api_key_here"
# Z.AI API для LLM, поиска и чтения (https://z.ai) ```bash
export ZAI_API_KEY="your_zai_api_key_here" 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 ```bash
# Вариант 1: через install.sh (интерактивно) # Через install.sh (интерактивно, ответить "y" на вопрос про wsl.conf)
./install.sh # ответьте "y" на вопрос про wsl.conf ./install.sh
# Вариант 2: вручную # Или вручную:
sudo tee -a /etc/wsl.conf <<'EOF' sudo tee -a /etc/wsl.conf <<'EOF'
[boot] [boot]
@@ -238,41 +111,93 @@ command = "/path/to/dotfiles/scripts/setup-hproxy.sh"
EOF EOF
``` ```
После изменения `wsl.conf` перезапустите WSL: `wsl --shutdown`. После изменения `wsl.conf` — `wsl --shutdown`. Обновить без перезапуска: `sudo scripts/setup-hproxy.sh` или `update_hproxy`.
Обновить `hproxy.local` без перезапуска WSL: **WSL Mirror mode** (`networkingMode=mirrored`) — IP не меняется, достаточно одной записи:
```bash
sudo scripts/setup-hproxy.sh
# или
update_hproxy # интерактивная функция из .bash_functions
```
**Mirror mode** (`networkingMode=mirrored` в `.wslconfig`) — WSL разделяет сетевой стек с хостом, IP не меняется. Достаточно один раз прописать запись в Windows hosts:
``` ```
# C:\Windows\System32\drivers\etc\hosts # C:\Windows\System32\drivers\etc\hosts
192.168.1.100 hproxy.local 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 может сообщить конфликт. Персональные настройки (`user.name`, `user.email`, `core.editor`, `core.sshCommand`) живут в `~/.gitconfig.local`.
Тогда сохраните старую версию и примените stow повторно:
```bash На Windows chezmoi при первом apply мигрирует существующий `~/.gitconfig` в `~/.gitconfig.local` и подставляет managed baseline. На Linux baseline задаётся вручную или через скрипты.
mv ~/.vscode-server/server-env-setup ~/.vscode-server/server-env-setup.bak.$(date +%Y%m%d%H%M%S)
stow -vt ~ vscode Проверка: `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`.