# Каталог компонентов окружения

По каждому: что это, откуда берется, как обнаружить, как поставить, как проверить, какие грабли.
Порядок разделов = порядок установки: зависимости идут раньше зависимых.

Колонка "группа" - для вопроса пользователю. Спрашивать группами, а не про каждый компонент.

| Группа | Компоненты | Кому нужно |
|---|---|---|
| ядро | скилы, правила, команды, скрипты набора | всем |
| 1С 8.x | плагин EDT, toolkit живой базы, малые MCP-серверы | разработка на 8.3 |
| 1С 7.7 | сервер метаданных 7.7, gcomp | сопровождение 7.7 |
| утилиты 1С | v8unpack, платформа 1С | сборка и разбор бинарников |
| документы | Node + docx, mermaid-cli | генерация docx и диаграмм |
| речь | transcribe, распознаватель, сервер локальных моделей | транскрибация встреч |
| обвязка | память между сессиями, CLI внешних моделей | память и кросс-ревью |

---

## Ядро: скилы, правила, команды, скрипты набора

**Что.** Содержимое этого репозитория: `skills/`, `rules/`, `commands/`, `scripts/`.

**Куда.** `~/.claude/skills/`, `~/.claude/rules/`, `~/.claude/commands/`, `~/.claude/scripts/`.

**Обнаружение.** Сравнить состав каталогов с составом репозитория. Для каждого совпавшего файла -
сравнение содержимого с игнором EOL (`diff -w --strip-trailing-cr`).

**Установка.** Пофайлово, по правилам из `safety.md` раздел 3: отсутствующее копировать, совпадающее
пропускать, расходящееся показывать пользователю. Наивное `cp -r skills/* ~/.claude/skills/`
затирает пользовательские доработки - так не делать.

**Проверка.** Скил виден агенту после перезапуска клиента; до перезапуска достаточно проверить, что
файл на месте и `SKILL.md` начинается с корректного frontmatter (`name`, `description`).

**Грабли.** Правила из `rules/` подключаются пользователем в его `CLAUDE.md` или настройках - само
копирование файла в `~/.claude/rules/` не включает правило автоматически. Об этом сказать в отчете.

---

## 1С 8.x: MCP-плагин для EDT

**Что.** MCP-сервер внутри 1С:EDT: семантический индекс BSL, метаданные, формы, валидация запросов,
отладка, обновление ИБ. В этом наборе описан плагин **AI-EDT** (ключ сервера `ai-edt`), см. скил
`ai-edt-tools`. Существуют и другие плагины под ту же задачу - у них свои имена инструментов
(развилка описана в шапке `ai-edt-tools/SKILL.md`).

**Обнаружение.** Порт HTTP-сервера AI-EDT задается в настройках EDT (Window > Preferences > AI-EDT),
по умолчанию `12250`; фактический URL записан в `.mcp.json` рабочей области - сначала читать его.
Порт занят процессом java из каталога EDT = плагин установлен и EDT запущена. Свободный порт
означает только, что сервер не запущен: EDT закрыта или плагин не установлен, по порту это не
различить - состояние `не отвечает`, а не `нет`. Порт `8765` принадлежит другому плагину
(EDT-MCP): занят он - установлен тот плагин, а не AI-EDT.

**Установка.** Плагин ставится в EDT ее собственным механизмом (update site), это делает пользователь
через интерфейс среды - агент за него в EDT не ходит. Задача агента: после установки добавить сервер
в `.mcp.json` воркспейса слиянием (`safety.md` раздел 2).

```json
{ "mcpServers": { "ai-edt": { "type": "http", "url": "http://127.0.0.1:12250/mcp" } } }
```

**Проверка.** Вызов `get_edt_version`. Ответ есть - плагин и EDT живы.

**Грабли.**
- У каждого воркспейса свой порт: несколько EDT одновременно - несколько записей с разными портами
  и разными ключами. Ключи не выдумывать, а согласовывать с пользователем.
- Плагин работает только при ЗАПУЩЕННОЙ EDT с открытым проектом. Молчание сервера чаще означает
  "EDT закрыта", а не "плагин сломан".
- Пока EDT держит файловую ИБ, пакетный запуск Конфигуратора по той же базе повиснет. Это защита, а
  не поломка.

---

## 1С 8.x: доступ к живой базе (1c-mcp-toolkit)

**Что.** HTTP API к запущенной информационной базе через внешнюю обработку. Скил `1c-mcp-toolkit`,
обработка лежит в самом скиле (`bin/`), исходники обработки - у ее авторов
(https://github.com/ROCTUP/1c-mcp-toolkit).

**Обнаружение.** `curl http://localhost:6003/health`. Типовые порты перебирает
`skills/1c-mcp-toolkit/scripts/health-probe.ps1`.

**Установка.** Отдельной установки не требует: обработка идет со скилом. Нужна платформа 1С и
информационная база. Запуск сеанса - скриптом `start-1c.ps1` из каталога `scripts/` самого скила `1c-mcp-toolkit`.

**Проверка.** `/health` отвечает `200`.

**Грабли.**
- Скрипты запускать в PowerShell 7 (`pwsh`), не в 5.1: на кириллице в JSON-телах 5.1 спотыкается.
- Без имени пользователя и пароля сеанс встает на форме авторизации, и HTTP-сервер не поднимается.
- Порт - на каждую базу свой; карту "база -> порт" держать в `CLAUDE.md` проекта, а не спрашивать
  каждый раз.

---

## 1С 8.x: малые MCP-серверы

**Что.** Отдельные серверы под узкие задачи, каждый на своем порту. Ключи, под которыми они
упоминаются в правилах и скилах набора:

| Ключ | Типовой порт | Задача | Скил |
|---|---|---|---|
| `bsl-platform-help` | 8003 | API платформы: методы, типы, сигнатуры, конструкторы | `1c-platform-docs` |
| `1c-naparnik` | 8007 | ревью кода, стандарты ИТС, документация конфигураций | `1c-naparnik` |
| `1c-mcp_ssl_server` | 8008 | поиск функций БСП по описанию задачи | `1c-ssl-patterns` |
| `1c-syntax-checker-mcp` | 8002 | синтаксис BSL без запущенной EDT | - |
| `1c-templates-mcp` | 8004 | шаблоны и заготовки кода | - |

**Обнаружение.** Занятость порта плюс `docker ps` - типично это контейнеры. Ключ должен быть в
`~/.claude/settings.json` (секция `mcpServers`, тип `http`).

**Установка.** Сами серверы в этот репозиторий не входят и ставятся отдельно, каждый по своей
документации; часть распространяется образами (например проверка синтаксиса - образ
`comol/1c_syntaxcheck_mcp` в Docker Hub), часть собирается из исходников. Задача агента - поднять
то, что у пользователя уже есть на диске, и прописать ключ в `settings.json` слиянием.

**Проверка.** Порт отвечает, контейнер в состоянии `healthy`, ключ виден в списке серверов сессии
после перезапуска клиента.

**Грабли.**
- Контейнер может быть `Up`, но `unhealthy` - это не работает. Проверять статус, а не факт запуска.
- Сервер отсутствует - это не блокер: правила набора описывают, что делать без него (см.
  `rules/mcp-tool-priority.md`, раздел "Когда инструменты недоступны").
- Ключи серверов писать ровно так, как в таблице: правила и скилы ссылаются на них дословно.

---

## 1С 7.7: сервер метаданных и gcomp

**Что.** `1c77-metadata` - разбор `1Cv7.MD` (объекты, реквизиты, модули, трассировка реквизита) вместо
ручного парсинга CP1251. `gcomp` - разбор и сборка `.ert` и `1Cv7.MD`. Скил `1c77-dev`.

**Обнаружение.** Порт сервера (типовой 8009) и наличие `gcomp` в PATH.

**Установка.** Сервер ставится отдельно: https://github.com/ivanarama/77MCP - оттуда же порядок
запуска. `gcomp` - внешняя утилита, ставится пользователем.

**Проверка.** `get_configuration_info` возвращает имя и версию загруженной конфигурации.

**Грабли.** Сервер читает КОНКРЕТНЫЙ файл конфигурации; при работе с другой базой конфигурацию надо
перезагрузить, иначе ответы будут про прошлую.

---

## Утилиты 1С: v8unpack, платформа

**Что.** `v8unpack` - распаковка и сборка `CF`/`CFE`/`EPF` без платформы (скил `v8unpack-cf`).
Платформа 1С нужна скилам групп `db-*`, сборке `EPF`/`ERF`, публикации через веб-сервер.

**Обнаружение.** `python -c "import v8unpack"` (или наличие консольной утилиты), каталог платформы
`1cv8`.

**Установка.** `v8unpack` - пакет с PyPI. Платформа - установщиком 1С, агент ее не ставит.

**Проверка.** Распаковать и собрать обратно заведомо валидный файл, сравнить результат.

**Грабли.** Версия утилиты пишется в метаданные распакованного дерева, и сборка проверяет совпадение
major.minor - смешивать версии распаковки и сборки нельзя.

---

## Документы: Node, docx, mermaid-cli

**Что.** `md-to-docx` (конвертация Markdown в DOCX) требует Node и npm-пакет `docx`.
`mermaid-render` требует `@mermaid-js/mermaid-cli` (команда `mmdc`).

**Обнаружение.** `node --version`, `mmdc --version`, наличие `node_modules/docx` рядом со скилом.

**Установка.** Node - установщиком; пакеты - через npm по инструкции соответствующего скила.

**Проверка.** Собрать минимальный документ и минимальную диаграмму, проверить, что файлы созданы и
непустые.

**Грабли.** `mmdc` тянет headless-браузер; в окружении без него рендер падает на запуске, а не на
разборе диаграммы - по тексту ошибки это не всегда очевидно.

---

## Речь: транскрибация и распознаватель

**Что.** Скил `transcribe` - транскрибация аудио и видео, локально и через облако. У него есть
собственный установщик, он и делает всю работу.

**Обнаружение.**

```bash
python ~/.claude/skills/transcribe/scripts/verify.py
```

**Установка.**

```bash
python ~/.claude/skills/transcribe/scripts/setup.py            # полный набор
python ~/.claude/skills/transcribe/scripts/setup.py --skip-models --skip-sherpa   # только транскрипция
```

Флаги установщика: `--skip-models`, `--skip-sherpa`, `--skip-gemini`, `--skip-whisper`,
`--with-pyannote`, `--allow-cpu`. На рабочей машине с уже собранными venv - обязательно
`--skip-whisper` и `--skip-sherpa`, иначе пересоздаст.

**Проверка.** `verify.py --full` - прогоняет тестовый файл целиком.

**Грабли.**
- **Два отдельных venv** - не прихоть: библиотеки распознавания и диаризации тянут несовместимые
  версии CUDA-библиотек и в одном окружении конфликтуют. Изоляция сделана процессами.
- Диаризация с автоопределением числа спикеров требует токена HuggingFace в `.env`; без него стадия
  просто не выполняется, остальное работает.
- Свой, уже настроенный распознаватель можно переиспользовать, не ставя второй: путь к его
  интерпретатору задается переменной `WHISPER_PYTHON` (в `.env` скила). Это же нужно, если
  распознаватель живет в отдельном проекте (например, голосовой ввод).
- Для локального разбора видео нужен сервер локальных моделей (адрес в `.env`, ключ `LOCAL_150_BASE`)
  с загруженными моделями зрения и текста. Сервер недоступен - речь и спикеры считаются, разбор
  экрана и саммари пропускаются; это штатная деградация, а не сбой.
- Ключи в `.env` вписывает пользователь. Файл не коммитить и не копировать между машинами вслепую.

---

## Обвязка: память между сессиями и CLI внешних моделей

**Что.** MCP-сервер памяти (`hindsight`) - семантический поиск по прошлым сессиям. CLI внешних
моделей - для кросс-ревью кода и планов чужой моделью, если у пользователя есть такие скилы
(в этот набор они не входят).

**Обнаружение.** Ключ `hindsight` в конфигурации MCP и ответ его адреса; `codex --version`,
`cursor-agent --version` в PATH.

**Установка.** Каждый ставится своим способом по документации; в этот набор они не входят.

**Проверка.** Для памяти - список банков; для CLI - вывод версии и один тестовый запуск на маленьком
входе.

**Грабли.**
- **Codex на Windows**: если в его конфиге режим песочницы выставлен в `elevated`, вспомогательный
  процесс требует прав администратора, и КАЖДЫЙ вызов падает мгновенно с ошибкой инициализации
  песочницы - при этом ревью выглядит как "замечаний нет". Рабочее значение - `unelevated`.
- **Большой ввод в CLI**: длинный diff, переданный аргументом командной строки, упирается в
  ограничение длины команды Windows. Обходится коротким промптом со ссылкой на файлы, которые модель
  прочитает сама.
- Память между сессиями индексирует диалоги в фоне; ручная запись фактов там обычно не нужна.

---

## Порядок установки (зависимости)

1. Базовое: Python, Node, Git, Docker, ffmpeg - то, на что опирается остальное.
2. Ядро набора (скилы, правила, команды, скрипты).
3. Платформенное: 1С, EDT с плагином.
4. Серверы: малые MCP, сервер метаданных 7.7, память.
5. Прикладное: transcribe, конвертеры документов, утилиты.
6. Обвязка: CLI внешних моделей.

Пункт 1 не ставится молча: отсутствие Docker или Node - это вопрос пользователю, а не самовольная
установка системного софта.

# Безопасность установки: как не сломать работающее окружение

Читать ДО первой записи в любой файл конфигурации. Все правила ниже написаны от одного риска: на
рабочей машине уже есть настроенный харнес, и установка не имеет права его испортить.

---

## 1. Резервная копия перед любой правкой

Перед первой записью в файл - копия с меткой времени рядом с оригиналом:

```bash
cp ~/.claude/settings.json ~/.claude/settings.json.bak-$(date +%Y%m%d-%H%M%S)
```

Копии не удалять по итогам установки: если что-то всплывет через неделю, откатываться будет нечем.
В отчете перечислить, какие копии созданы и где лежат.

Каталоги (`skills/`, `rules/`) целиком не копируются - там копия делается пофайлово, только для тех
файлов, которые реально перезаписываются.

---

## 2. Конфиги MCP: слияние, а не перезапись

**Никогда не писать файл конфигурации целиком из шаблона.** В нем лежат вещи, о которых установка не
знает: чужие серверы, права, хуки, переменные окружения, токены.

Файлов три, и они разные:

| Файл | Что там | Кто пишет |
|---|---|---|
| `~/.claude/settings.json` | пользовательские настройки, часть MCP-серверов, права, хуки, env | правится осознанно |
| `~/.claude.json` | состояние клиента плюс часть MCP-серверов | правится осторожно, там же служебное состояние |
| `<проект>/.mcp.json` | серверы конкретного воркспейса (обычно там EDT-сервер проекта) | правится по проекту |

Порядок правки: прочитать JSON -> добавить ТОЛЬКО отсутствующие ключи -> записать обратно.

```python
import json, shutil, time
from pathlib import Path

p = Path.home() / ".claude" / "settings.json"
shutil.copy(p, p.with_suffix(f".json.bak-{time.strftime('%Y%m%d-%H%M%S')}"))
data = json.loads(p.read_text(encoding="utf-8"))
servers = data.setdefault("mcpServers", {})
if "новый-сервер" not in servers:          # ключ УЖЕ есть - не трогаем, это выбор пользователя
    servers["новый-сервер"] = {"type": "http", "url": "http://localhost:PORT/mcp"}
    p.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
```

Ключ уже занят под другой адрес - это **конфликт**, а не повод перезаписать: показать пользователю
обе стороны и спросить.

**Секреты в конфигах.** В `settings.json` бывают токены в `env`. Не печатать их значения в вывод, не
копировать в отчеты, не выносить в резервные копии за пределы домашнего каталога.

---

## 3. Скилы, правила, команды: конфликт - это диалог, а не перезапись

Три состояния файла из набора:

1. **Нет у пользователя** - копировать смело.
2. **Есть, содержимое совпадает** - пропустить молча.
3. **Есть, содержимое отличается** - НЕ перезаписывать. Показать `diff` и спросить.

Третий случай - основной на рабочей машине: пользователь дорабатывает скилы под себя. Наивное
`cp -r skills/* ~/.claude/skills/` затирает эти доработки без следа - именно поэтому установка идет
пофайлово.

```bash
diff -u ~/.claude/skills/<скил>/SKILL.md skills/<скил>/SKILL.md
```

Сравнивать с игнором концов строк: репозиторий может хранить CRLF, рабочая копия - LF, и тогда
diff покажет весь файл измененным на ровном месте.

```bash
diff -w --strip-trailing-cr ~/.claude/rules/<файл>.md rules/<файл>.md
```

**Чужие скилы не трогать вообще.** Все, чего нет в наборе, - это либо скилы пользователя, либо
скилы плагинов. Ни удалять, ни переименовывать, ни "приводить к единому виду".

---

## 4. Чего не касаться никогда

- **Запущенные сеансы 1С и EDT.** Не завершать процессы `1cv8`, `1cv8c`, EDT (`javaw` из каталога
  платформы). В них может идти работа пользователя, а у EDT еще и монополия на файловую ИБ.
- **Существующие контейнеры Docker.** Не делать `down`, `rm`, `prune`. Только запуск недостающего.
  Контейнер помечен `unhealthy` - это диагноз в отчет, а не повод пересоздать.
- **Готовые venv.** Не пересоздавать существующий - там могут стоять руками собранные колеса под
  конкретные CUDA/cuDNN. У установщика `transcribe` для этого есть `--skip-whisper` и `--skip-sherpa`.
- **Пользовательские данные.** `transcribe/voiceprints/` (голоса - чувствительные данные),
  `.env` с ключами, `~/.claude/projects/*/memory/`, `~/.claude/plans/`.
- **Порт, занятый чужим процессом.** Не пытаться освободить. Сообщить, кто занял, и предложить
  другой порт.

---

## 5. Идемпотентность

Повторный запуск установки на уже настроенной машине обязан быть безвредным: ничего не дублировать,
ничего не перезаписывать заново, не плодить контейнеры и записи в конфигах. Проверка простая -
второй прогон подряд должен дать план, в котором все компоненты в состоянии "есть и отвечает", а
список действий пуст.

Частая ошибка обратного свойства: запуск контейнера командой, которая каждый раз создает новый
экземпляр. Это накапливается незаметно (десяток копий одного образа за сутки) и съедает память.
Перед запуском проверять, что контейнер с таким именем уже не работает.

---

## 6. Откат

Порядок при неудаче:

1. Остановиться на упавшем компоненте, остальные не откатывать - они не при чем.
2. Вернуть файлы конфигурации из копий, созданных по разделу 1.
3. Записать в отчет: что делали, на чем упало, что вернули, что осталось в промежуточном состоянии.
4. Не пытаться "дочинить" тем же способом повторно. Два неудачных захода одним подходом - повод
   остановиться и спросить пользователя.

---

## 7. Что требует действий пользователя, а не установки

Перечислять в отчете отдельным списком, потому что агент это сделать не может:

- **Перезапуск Claude Code** - новые MCP-серверы подхватываются только при старте клиента.
- **Ключи и токены** - `GEMINI_API_KEY`, `HF_TOKEN` и прочие пользователь вписывает сам.
- **Плагины в среде разработки** - установка плагина в EDT идет через ее интерфейс.
- **Права и учетные записи 1С** - пароли к информационным базам агент не выдумывает и не хранит.