1c-bsp-api · git:20260820.edb237f · 2026-08-20 · sha256 6721e815d5151e3b
1c-bsp-api git:20260820.edb237fA
Immutable. This exact content is served forever at /api/v1/blob/6721e815d5151e3b.
---
name: 1c-bsp-api
description: "Справочник программного интерфейса Библиотеки стандартных подсистем (БСП) 1С - какие общие модули существуют, какие у них экспортные методы, сигнатуры, типы параметров, контексты выполнения и переопределяемые обработчики. Используй когда пишешь код на конфигурации с БСП и нужно узнать имя модуля или метода, его сигнатуру, серверный он или клиентский, какой переопределяемый обработчик реализовать под задачу; а также чтобы ПРОВЕРИТЬ вызов перед тем, как его написать: имя модуля БСП, отсутствующее в библиотеке, по виду не отличается от настоящего, поэтому вызов сверяется со справочником. Работает офлайн, платформа и EDT не нужны. НЕ для API самой платформы (там 1c-platform-docs) и НЕ для прикладных конфигураций ERP, ЗУП, БП"
argument-hint: "find <текст> | show <Модуль.Метод> | check <Модуль.Метод> | module <Имя> | subsystem <Имя> | overrides <текст>"
allowed-tools:
- Bash
- Read
---
# Справочник API БСП
Офлайн-справочник по программному интерфейсу БСП: 2624 метода в 284 модулях, 71 подсистема,
версии 3.1.11 и 3.2.1. Собран из двух источников одновременно - структура и сигнатуры из
документации, модули и экспортность из самой библиотеки. Каждая версия документации сведена со
своим дистрибутивом, поэтому различия между версиями видны, а не усреднены.
Назначение написано нами: одна строка у каждого из 284 модулей и у 440 методов ядра. Описательный
текст документации ИТС в справочник не переносится.
Справочник больше мегабайта, в контекст целиком не грузится. Он спрашивается по месту.
## Главное правило
**Не пиши вызов метода БСП, не проверив его.** Имена в БСП длинные и составные, поэтому
правдоподобная выдумка выглядит как настоящее имя. Классические несуществующие:
`ФайловаяСистемаКлиентСервер`, `JSONСтрокой`, `Пользователи.СсылкаТекущегоПользователя`.
```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ФайловаяСистемаКлиентСервер.ПолучитьФайл
```
Код возврата 1, если вызова нет. При промахе инструмент подсказывает похожие имена - и по
модулю, и по методу.
## Как устроена библиотека
**Суффикс имени модуля - это контекст выполнения, а не тематика.** Один механизм разложен по
нескольким модулям, и выбор между ними определяется тем, откуда идет вызов:
| Суффикс | Где исполняется | Пример |
|---|---|---|
| без суффикса или `Сервер` | сервер, толстый клиент, внешнее соединение | `ОбщегоНазначения` |
| `Клиент` | тонкий и толстый клиент | `ОбщегоНазначенияКлиент` |
| `КлиентСервер` | и там, и там | `ОбщегоНазначенияКлиентСервер` |
| `ВызовСервера` | сервер, вызывается с клиента напрямую | `ОбщегоНазначенияВызовСервера` |
Отсюда частая ошибка: серверный метод вызывают из клиентского кода. Контекст каждого метода есть
в справочнике, отбор - ключом `--av` (`S` сервер, `T` тонкий, `F` толстый, `E` внешнее
соединение, `C` вызов сервера).
**Три вида модулей по назначению:**
- **Обычные** - публичный интерфейс, их и вызывают: `ОбщегоНазначения`, `Пользователи`,
`УправлениеПечатью`.
- **`Переопределяемый`** - точки расширения. Их не вызывают, в них ПИШУТ: обработчик вызывает
библиотека, а тело пишет внедряющая конфигурация. Таких методов 372.
- **`Служебный`** - внутренняя реализация библиотеки. В программный интерфейс не входит ни один
служебный метод, и вызывать их нельзя: они меняются между версиями без объявления.
Еще два суффикса встречаются реже: `ПовтИсп` - модуль с повторным использованием возвращаемых
значений, `Локализация` - национальная специфика.
**Часть интерфейса объявлена не в общих модулях.** Обмен данными опубликован модулями объектов
обработок (`Обработка.УниверсальныйОбменДаннымиXML`, `Обработка.КонвертацияОбъектовXDTO`).
В справочнике они есть наравне с общими модулями.
## Запросы
```bash
B=skills/1c-bsp-api/scripts/bsp-api.py
python $B find печать # поиск по имени, модулю, подсистеме, назначению
python $B find "реквизит объект" # ищутся все слова запроса сразу, не подстрока
python $B find файл --av T # только то, что доступно на тонком клиенте
python $B show ОбщегоНазначения.ЗначениеРеквизитаОбъекта # карточка метода
python $B show ЗначениеРеквизитаОбъекта # все модули, где есть метод с таким именем
python $B module Пользователи # состав модуля целиком
python $B modules контакт # какие вообще есть модули
python $B subsystem печать # модули и механизмы подсистемы
python $B overrides обновлен # переопределяемые обработчики под задачу
python $B check Пользователи.ТекущийПользователь
python $B stats # что вообще в справочнике
```
Общие ключи отбора: `--av`, `--sub <подсистема>`, `--version 3.2.1`, `--limit N`.
## Как читать выдачу
Строка вида `ОбщегоНазначения.ЗначениеРеквизитаОбъекта SFE` - это модуль, метод и контексты.
**Пометка `[?]` означает, что модуль выведен, а не подтвержден.** Документация БСП называет
механизм, а не модуль, поэтому у части методов модуль восстановлен по примеру вызова или по
совпадению контекстов. В карточке (`show`) последняя строка всегда говорит, откуда взято имя
модуля. Метод с пометкой перед использованием стоит сверить с конфигурацией проекта.
Пометка стоит у 117 методов из 2624, это около четырех процентов. Еще у 37 модуль определить
не удалось вовсе - они собраны под именем `?`. Это не значит, что метода нет: значит, одно и то же
имя объявлено в нескольких модулях, и документация не говорит, о каком из них статья.
**Пометка `[!]` означает, что между версиями метод изменился.** Карточка тогда содержит строку
"ВНИМАНИЕ, в <версия> иначе" с прежней сигнатурой. Таких методов 27, и часть изменений ломающие:
`ОбщегоНазначения.ВыполнитьМетодКонфигурации` из процедуры стал функцией, а у
`ДобавитьПоказатель` новый параметр вставлен не в конец, а первым. Код, написанный по новой
сигнатуре, на старой версии передаст аргументы не туда и об этом не сообщит.
## Частые ошибки
- **Выдуманный модуль.** Проверять `check`, а не полагаться на память.
- **Серверный метод в клиентском коде.** Смотреть контексты; для клиента почти всегда есть
парный модуль с суффиксом `Клиент`.
- **Вызов служебного модуля.** Если в имени есть `Служебный` - это не интерфейс.
- **Попытка вызвать переопределяемый обработчик.** В него пишут тело, а не вызывают его.
- **Метод из другой версии.** У каждой записи указано, в каких версиях БСП она есть. Метод,
помеченный только `3.2.1`, на 3.1.11 не существует. А метод с пометкой `[!]` существует в обеих,
но вызывается по-разному - смотреть карточку до того, как писать вызов.
- **Расчет на то, что у метода тот же набор параметров, что был раньше.** Сигнатура в
справочнике полная, включая значения по умолчанию - брать оттуда.
## Границы
Справочник знает ИМЕНА, СИГНАТУРЫ и КОНТЕКСТЫ, а назначение - строкой, написанной нами. Развернутого
описания в нем нет: текст документации ИТС лицензионный и сюда не переносится. Строка назначения есть
у каждого модуля, но у методов пока только у ядра - базовых модулей `ОбщегоНазначения*`, длительных
операций, пользователей, строковых функций, файловой системы и журнала регистрации. Когда нужно
понять механизм глубже, а не форму вызова - идти в документацию ИТС по подсистеме, которую покажет
`subsystem`.
Не покрыты: HTTP-сервисы и веб-сервисы библиотеки, макеты, роли, права, состав метаданных
подсистем. Только программный интерфейс кода.
## Сборка справочника
Готовый справочник лежит в `references/bsp-api.jsonl` и обновлять его нужно только при переходе
на новую версию БСП. Пересборка требует двух источников, оба лицензионные и в репозиторий не
входят: скрапа документации с ИТС и дистрибутива библиотеки.
```bash
python -m v8unpack -E 1Cv8.cf E:\bsp\3_2_1 --temp E:\bsp\_tmp # распаковать дистрибутив
python skills/1c-bsp-api/scripts/bsp-build.py \
--docs "3.1.11=E:\scrape\bsp3111doc" --docs "3.2.1=E:\scrape\bsp321doc" \
--lib "3.1.11=E:\bsp\3_1_11" --lib "3.2.1=E:\bsp\3_2_1" \
--purposes skills/1c-bsp-api/references/purposes.json \
--out skills/1c-bsp-api/references/bsp-api.jsonl \
--map skills/1c-bsp-api/references/subsystem-map.md
```
Формулировки назначения ведутся отдельно, в `references/purposes.json`: раздел `modules` и раздел
`methods` с ключами вида `Модуль.Метод`. При сборке они подмешиваются в справочник, а имена, которых
в нем нет, генератор называет в отчете - это ловит и опечатку, и формулировку к методу, которого
в этой версии уже не существует.
Ключи `--docs` и `--lib` указываются по одному на версию и связываются префиксом. Связывать
обязательно: если сшивать документацию 3.1.11 с библиотекой 3.2.1, методы, убранные в новой
версии, будут объявлены несуществующими. Библиотека без префикса версии берется для всех.
Брать надо `1Cv8.cf` - чистую библиотеку, а не `1Cv8_demo.cf`: демонстрационная конфигурация
несет объекты, которых в поставке нет. Распаковка идет без платформы и Конфигуратора.
Скрипты на Python, PowerShell-порта нет: сборка нужна редко, а поиск идет по готовому файлу.