mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-06-26 15:04:34 +03:00
Nick Shirokov
26888a07d5
Приводим авторский контент (.ps1/.psm1/.py/.mjs/.md/.json, пин .bsl) к единому LF и закрепляем политикой в .gitattributes. Инструмент правки всегда пишет LF, поэтому единый LF убирает EOL-шум в диффах, ложные срабатывания blame и налог на ручную синхронизацию CRLF-файлов. BOM на .ps1 сохранён (git с eol=lf меняет только CR<->LF, BOM не трогает). Данные 1С (*.xml) и бинарники под нормализацию не берём. Гейт: PS-порт 459/459, Python-порт 459/459, web-test E2E 22/22 (с пересборкой стенда). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
252 lines
16 KiB
Markdown
252 lines
16 KiB
Markdown
# Конфигурация проекта (.v8-project.json)
|
||
|
||
Файл `.v8-project.json` — единый конфиг проекта для всех навыков Claude Code. Хранит пути к платформе 1С, список баз данных и настройки инструментов (Apache, ffmpeg, TTS).
|
||
|
||
Размещается в корне проекта (рядом с `.git/`). Создаётся навыком `/db-list add` или вручную.
|
||
|
||
> **Шаблон**: в корне репозитория лежит `.v8-project.example.json` — скопируйте его в `.v8-project.json` и поправьте пути под свою машину.
|
||
|
||
> **Безопасность**: файл содержит секреты (пароли баз данных, API-ключи TTS) и добавлен в `.gitignore` — он не попадает в репозиторий. Каждый разработчик заводит свой `.v8-project.json` локально. Пример (`.v8-project.example.json`) секретов не содержит и хранится в репозитории.
|
||
|
||
## Полная схема
|
||
|
||
```jsonc
|
||
{
|
||
// === Платформа ===
|
||
"v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
|
||
|
||
// === Базы данных ===
|
||
"databases": [
|
||
{
|
||
"id": "dev", // уникальный идентификатор
|
||
"name": "Разработка", // отображаемое имя
|
||
"type": "file", // "file" или "server"
|
||
"path": "C:\\Bases\\MyApp_Dev", // каталог (для file)
|
||
"user": "Admin", // пользователь 1С
|
||
"password": "", // пароль
|
||
"aliases": ["dev", "разработка"], // альтернативные имена
|
||
"branches": ["dev", "feature/*"], // привязка к Git-веткам
|
||
"configSrc": "src\\cf", // каталог XML-выгрузки конфигурации (см. структуру ниже)
|
||
"webUrl": "http://localhost:8081/dev" // URL веб-клиента (для /web-test)
|
||
},
|
||
{
|
||
"id": "test",
|
||
"name": "Тестовая",
|
||
"type": "server", // серверная база
|
||
"server": "srv01", // адрес сервера 1С
|
||
"ref": "MyApp_Test", // имя базы на сервере
|
||
"user": "Admin",
|
||
"password": "123",
|
||
"aliases": ["test", "тест"]
|
||
}
|
||
],
|
||
"default": "dev",
|
||
|
||
// === Инструменты ===
|
||
"webPath": "C:\\tools\\apache24", // каталог Apache
|
||
"ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe", // путь к ffmpeg
|
||
"tts": { // настройки озвучки
|
||
"provider": "edge",
|
||
"voice": "ru-RU-DmitryNeural"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Корневые поля
|
||
|
||
| Поле | Тип | Обяз. | По умолчанию | Описание | Кто заполняет |
|
||
|------|-----|:-----:|-------------|----------|---------------|
|
||
| `v8path` | string | да | — | Путь к каталогу `bin` платформы 1С (или к файлу `1cv8.exe`/`ibcmd.exe`, см. ниже) | `/db-list add` или руками |
|
||
| `databases` | array | да | — | Список баз данных | `/db-list add` |
|
||
| `default` | string | нет | — | `id` базы по умолчанию | `/db-list` |
|
||
| `editingAllowedCheck` | `"deny"`/`"warn"`/`"off"` | нет | `deny` | Глобальная реакция support-guard на правку объектов на замке (см. ниже) | Руками |
|
||
| `skillSuggester` | `"on"`/`"off"` | нет | `on` | Подсказки навыков от хука skill-suggester (только если хук включён, см. ниже) | Руками |
|
||
| `webPath` | string | нет | `tools/apache24` | Каталог Apache HTTP Server | Руками |
|
||
| `ffmpegPath` | string | нет | `tools/ffmpeg/bin/ffmpeg.exe` | Путь к ffmpeg | Руками |
|
||
| `tts` | object | нет | Edge TTS, DmitryNeural | Настройки озвучки видео | Руками |
|
||
|
||
## Базы данных (`databases[]`)
|
||
|
||
| Поле | Тип | Обяз. | Описание | Кто заполняет |
|
||
|------|-----|:-----:|----------|---------------|
|
||
| `id` | string | да | Уникальный идентификатор | `/db-list add` |
|
||
| `name` | string | да | Отображаемое имя | `/db-list add` |
|
||
| `type` | `"file"` / `"server"` | да | Тип подключения | `/db-list add` |
|
||
| `path` | string | для file | Каталог файловой базы | `/db-list add` |
|
||
| `server` | string | для server | Адрес сервера 1С | `/db-list add` |
|
||
| `ref` | string | для server | Имя базы на сервере | `/db-list add` |
|
||
| `user` | string | нет | Пользователь 1С | `/db-list add` или руками |
|
||
| `password` | string | нет | Пароль | `/db-list add` или руками |
|
||
| `aliases` | string[] | нет | Альтернативные имена для обращения к базе | `/db-list add` или руками |
|
||
| `branches` | string[] | нет | Git-ветки или glob-паттерны (`release/*`, `feature/*`) | Руками |
|
||
| `configSrc` | string | нет | Каталог XML-выгрузки конфигурации (рекомендуется `src/cf`, см. структуру ниже). Путь относительный — от корня проекта | Руками |
|
||
| `editingAllowedCheck` | `"deny"`/`"warn"`/`"off"` | нет | Override реакции support-guard для этой базы (см. ниже) | Руками |
|
||
| `skillSuggester` | `"on"`/`"off"` | нет | Override подсказок навыков для этой базы (см. ниже) | Руками |
|
||
| `webUrl` | string | нет | URL веб-клиента для `/web-test` | Руками |
|
||
|
||
### Support-guard и `editingAllowedCheck`
|
||
|
||
Навыки-мутаторы (`meta-edit`, `meta-compile`, `meta-remove` и др.) перед изменением исходников проверяют состояние поддержки конфигурации (`Ext/ParentConfigurations.bin`, см. [1c-support-state-spec.md](1c-support-state-spec.md)). Если объект «на замке» поставщика (или вся конфигурация read-only, или удаляется не снятый с поддержки объект), правка по умолчанию **блокируется** — прямое изменение сломало бы обновления.
|
||
|
||
Реакцию задаёт `editingAllowedCheck`:
|
||
- `deny` (по умолчанию, в т.ч. когда поле не задано) — блокировать с диагностикой;
|
||
- `warn` — пропускать, но писать предупреждение;
|
||
- `off` — проверку не выполнять.
|
||
|
||
Триггер проверки — наличие `ParentConfigurations.bin` (конфигурация на поддержке), а не регистрация в `.v8-project.json`. Поле лишь меняет реакцию. Берётся `databases[].editingAllowedCheck` базы, чей `configSrc` охватывает редактируемый путь; иначе — корневое `editingAllowedCheck`; иначе `deny`.
|
||
|
||
### Хуки и `skillSuggester` (экспериментально)
|
||
|
||
Помимо встроенной в навыки проверки (выше), есть **опциональные хуки Claude Code** (каталог `hooks/`), которые по умолчанию **выключены** и подключаются вручную (см. `hooks/README.md`):
|
||
- **support-guard** — перехватывает правки исходников на поддержке **в обход навыков** (прямые `Edit`/`Write`); реакцию берёт из того же `editingAllowedCheck`;
|
||
- **skill-suggester** — ненавязчиво подсказывает профильный навык, когда модель работает с исходниками напрямую.
|
||
|
||
`skillSuggester` (`on`/`off`, по умолчанию `on`) включает/выключает подсказки skill-suggester. Действует только когда хук подключён; раскладка та же — `databases[].skillSuggester` для базы по `configSrc`, иначе корневое, иначе `on`.
|
||
|
||
### Разрешение базы
|
||
|
||
Все навыки `/db-*`, `/epf-build`, `/epf-dump`, `/erf-build`, `/erf-dump`, `/web-publish` используют единый алгоритм:
|
||
|
||
1. Если пользователь указал **параметры подключения** (путь, сервер) — используются напрямую
|
||
2. Если указал **базу по имени** — поиск: `id` → `aliases` (с учётом морфологии) → `name` (нечёткое)
|
||
3. Если **не указал** — сопоставление текущей ветки Git с `branches` (точно или по glob-паттерну)
|
||
4. Fallback на `default`
|
||
5. Если не найдено — Claude спросит пользователя
|
||
6. Если база не зарегистрирована — Claude предложит `/db-list add`
|
||
|
||
## Настройки инструментов
|
||
|
||
### `webPath` — Apache HTTP Server
|
||
|
||
Путь к каталогу Apache. Используется навыками `/web-publish`, `/web-info`, `/web-stop`, `/web-unpublish`.
|
||
|
||
Если не задан — ищется в `tools/apache24` от корня проекта. При первом вызове `/web-publish` Apache скачивается автоматически.
|
||
|
||
Подробнее — в [гайде по веб-публикации](web-guide.md).
|
||
|
||
### `ffmpegPath` — ffmpeg
|
||
|
||
Путь к исполняемому файлу ffmpeg. Используется навыком `/web-test` для записи видео.
|
||
|
||
Если не задан — ищется по порядку:
|
||
1. `tools/ffmpeg/bin/ffmpeg.exe` (от корня проекта)
|
||
2. `ffmpeg` в системном PATH
|
||
|
||
Подробнее — в [гайде по записи видео](web-test-recording-guide.md).
|
||
|
||
### `tts` — озвучка видеоинструкций
|
||
|
||
| Поле | Тип | По умолчанию | Описание |
|
||
|------|-----|-------------|----------|
|
||
| `provider` | string | `"edge"` | Провайдер: `"edge"`, `"elevenlabs"`, `"openai"` |
|
||
| `voice` | string | `"ru-RU-DmitryNeural"` | Голос (имя или ID в зависимости от провайдера) |
|
||
| `apiKey` | string | — | API-ключ (для elevenlabs, openai) |
|
||
| `apiUrl` | string | — | URL сервиса (для openai-совместимых) |
|
||
| `model` | string | — | Модель (для openai) |
|
||
|
||
Подробнее о выборе провайдера и голосов — в [гайде по записи видео](web-test-recording-guide.md#доступные-голоса-и-провайдеры).
|
||
|
||
### `webUrl` — URL веб-клиента (per-database)
|
||
|
||
URL для открытия базы в браузере через `/web-test`. Задаётся в записи конкретной базы.
|
||
|
||
Если не задан — `/web-test` берёт URL из активной веб-публикации (`/web-publish`).
|
||
|
||
Полезно, если веб-клиент доступен по нестандартному адресу (другой порт, внешний сервер, reverse proxy).
|
||
|
||
## Рекомендуемая структура проекта
|
||
|
||
Исходники 1С удобно держать под единым каталогом `src/`:
|
||
|
||
```
|
||
src/
|
||
cf/ # XML-выгрузка конфигурации (configSrc базы → "src\\cf")
|
||
cfe/<ИмяРасширения>/ # исходники расширения (CFE)
|
||
epf/<ИмяОбработки>/ # исходники внешней обработки (EPF)
|
||
erf/<ИмяОтчёта>/ # исходники внешнего отчёта (ERF)
|
||
```
|
||
|
||
В `.v8-project.json` напрямую участвует только `cf` — через поле `configSrc` базы (`"src\\cf"`).
|
||
Каталоги `cfe`/`epf`/`erf` в конфиг не прописываются: их пути передаются соответствующим навыкам
|
||
аргументами при сборке/разборке (`epf-build -SourceFile src\\epf\\<Имя>\\<Имя>.xml`,
|
||
`cfe-borrow -SrcDir src\\cfe\\<Имя>` и т.п.). Структура — соглашение, а не требование; навыки работают
|
||
с любыми путями.
|
||
|
||
## Движок: 1cv8 или ibcmd
|
||
|
||
По умолчанию навыки `/db-*`, `/epf-*`, `/erf-*` работают через конфигуратор (`1cv8.exe`; путь к нему
|
||
определяется автоматически по каталогу `v8path`) — менять это не нужно.
|
||
|
||
При желании ту же операцию можно выполнить через автономный сервер `ibcmd`. Для этого навык должен
|
||
получить путь к самому файлу `ibcmd.exe` (каталог `bin` всегда трактуется как `1cv8.exe`). Путь
|
||
указывают одним из двух способов:
|
||
- **разово, в самой задаче** — назвать полный путь к `ibcmd.exe`, например
|
||
`C:\\Program Files\\1cv8\\8.3.24.1691\\bin\\ibcmd.exe`;
|
||
- **в файле настроек** — прописать в `v8path` не каталог `bin`, а сам файл `...\\bin\\ibcmd.exe` (тогда через
|
||
`ibcmd` пойдут все операции).
|
||
|
||
Через `ibcmd` поддерживаются только файловые базы. Какие именно навыки это умеют — в [руководстве по базам](db-guide.md#движок-1cv8-или-ibcmd).
|
||
|
||
## Минимальный пример
|
||
|
||
```json
|
||
{
|
||
"v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
|
||
"databases": [
|
||
{
|
||
"id": "dev",
|
||
"name": "Разработка",
|
||
"type": "file",
|
||
"path": "C:\\Bases\\MyApp"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## Полный пример
|
||
|
||
```json
|
||
{
|
||
"v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
|
||
"databases": [
|
||
{
|
||
"id": "dev",
|
||
"name": "Разработка",
|
||
"type": "file",
|
||
"path": "C:\\Bases\\MyApp_Dev",
|
||
"user": "Admin",
|
||
"password": "",
|
||
"aliases": ["dev", "разработка"],
|
||
"branches": ["dev", "develop", "feature/*"],
|
||
"configSrc": "src\\cf",
|
||
"webUrl": "http://localhost:8081/dev"
|
||
},
|
||
{
|
||
"id": "test",
|
||
"name": "Тестовая",
|
||
"type": "server",
|
||
"server": "srv01",
|
||
"ref": "MyApp_Test",
|
||
"user": "Администратор",
|
||
"password": "",
|
||
"aliases": ["test", "тест", "тестовая"],
|
||
"branches": ["main", "release/*"]
|
||
}
|
||
],
|
||
"default": "dev",
|
||
"webPath": "C:\\tools\\apache24",
|
||
"ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe",
|
||
"tts": {
|
||
"provider": "edge",
|
||
"voice": "ru-RU-DmitryNeural"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Связанные навыки
|
||
|
||
- [Базы данных](db-guide.md) — `/db-list`, `/db-create`, `/db-load-xml`, `/db-dump-xml` и другие
|
||
- [Веб-публикация](web-guide.md) — `/web-publish`, `/web-info`, `/web-stop`
|
||
- [Тестирование в браузере](web-test-guide.md) — `/web-test`
|
||
- [Запись видеоинструкций](web-test-recording-guide.md) — запись видео, субтитры, озвучка
|