source-access · git:20261013.179d77a · 2026-10-13 · sha256 d8783fddcbfb3925
source-access git:20261013.179d77aA
Immutable. This exact content never changes and is served at /api/v1/blob/d8783fddcbfb3925.
---
name: source-access
description: Навигация по исходникам 1С логическим адресом — найти цель, прочитать узел, спуститься по ветвям, сравнить два узла. Используй когда нужно понять состав объекта, формы, роли, схемы компоновки или модуля
argument-hint: <объект|путь|адрес>
allowed-tools:
- Read
- Glob
---
# /source-access — чтение исходников логическим адресом
## MCP routing
- Всё чтение исходников идёт одним MCP `unica`: `unica.search` ищет цель по
имени или в тексте BSL, `unica.view` читает узел по адресу,
`unica.diff` сравнивает два узла, `unica.check` отвечает о готовности набора.
- Не вызывай внутренние MCP/CLI-адаптеры и не подменяй логическую цель
физическим путём.
- Чтение не меняет исходники. Правка идёт одним `unica.apply`: BSL —
операциями `code.insert` и `code.replace`, предметные описания — операциями
своего семейства. Сначала получи план вызовом `unica.apply` с `at` и `ops`.
Для операций СКД прочитай подробный контракт выбранной операции адресом
`<узел>.Can.<операция>` в `unica.view`, например
`cf:Report.F05Report.Template.F05Schema.DataSet.F05Data.Query.Can.query.set` на
запросе существующего набора данных или на узле варианта. Операция подузла —
поля, параметра, варианта — читается на его адресе (`…Field.<поле>`,
`…Parameter.<параметр>`, `…Setting.<вариант>`), а создающая операция — на
родителе. Применимые адреса, аргументы и последствия даёт этот контракт. Предметные пояснения группировок,
параметров и границы создания схемы — в
[справке по отчётам](../../references/use-cases/reports-printing.md).
Для табличного макета прочитай `<Template>.Can.area.add` на самом Template —
новую область создаёт он, и `<Template>.Area.<область>.Can.mxl.set` на
существующей области — её ячейки правит он; сам макет создаёт
`template.add` на владельце. Читать макет можно шире, чем править:
подробный контракт объясняет сохраняемый профиль и отказы. Предметная
[справка по печати](../../references/use-cases/reports-printing.md)
объясняет области, параметры и предел полной сборки DSL.
## Адрес
```
<набор исходников>:<Вид>[.<Имя>[.<Ветвь>[.<Имя>...]]]
```
`main:Catalog.Валюты` — объект, `main:Catalog.Валюты.Form.ФормаЭлемента` — его
форма, `main:Catalog.Валюты.Module.Object.Method.ПередЗаписью` — метод модуля
объекта. Вид цели задаёт число сегментов: прикладное имя, совпадающее с
названием вида, объект в ветвь не превращает.
Префикс набора обязателен. Адрес без него отклоняется кодом `bad_value` с
подсказкой вызвать `unica.view {}`.
`unica.resolve {at}` возвращает расположение существующего узла. Для владельца
общего модуля это XML-дескриптор; для его `Method`, `Body` и вложенной `Region`
— файл BSL и диапазон строк самого узла. Реквизит объекта указывает на XML
объекта, элемент формы — на `Ext/Form.xml`; у них `lines.state: "notLineBased"`.
Отсутствующий узел даёт `not_found`, даже если его владелец существует.
Обратный вызов `unica.resolve {path}` определяет объект по раскладке файлов.
Одного пути к файлу недостаточно, чтобы выбрать конкретный метод или элемент:
несколько узлов находятся в одном файле.
## Порядок работы
1. `unica.view {}` без аргументов — корень: наборы исходников, их формат,
готовность и незакрытые проверки. Отсюда берётся имя набора для префикса.
2. `unica.search {corpus: "names"}` переводит в адрес имя или синоним.
`kind` сужает вид, `limit` ограничивает страницу. Путь, пришедший
снаружи, переводит `unica.resolve` — аварийный выход, а не обычный ход.
3. `unica.view {at}` читает узел. Ответ бывает двух форм, и различать их надо
до чтения полей:
- **узел** — `props` с фактами самого узла и `branches` со счётчиками
дочерних коллекций;
- **страница коллекции** — `items`, каждый со своим `at`.
4. Спускайся по адресу из `branches`, пока не дойдёшь до нужного факта.
Содержимое лежит в листьях: текст запроса — в `...DataSet.<Набор>.Query`,
текст метода — в `...Method.<Имя>.Body`, оба построчно с `line` и `text`.
### Корень
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": { "name": "unica.view", "arguments": { "cwd": "<workspace>" } }
}
```
### Поиск цели
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "unica.search",
"arguments": { "cwd": "<workspace>", "corpus": "names", "query": "Валюты", "kind": "Form" }
}
}
```
Попадание несёт `at`, `kind` и `title`. Физического пути в ответе нет: путь
живёт только в аварийном `unica.resolve`. Признак `approximate` означает, что
совпало по близости, а не точно. Если `sourceCoverage.complete: false`,
часть дескрипторов не прочитана; пустой ответ тогда не доказывает отсутствия
объекта. Причина и число пропусков находятся в `sourceCoverage.details` и
`sourceCoverage.omitted`.
### Чтение узла
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "unica.view",
"arguments": {
"cwd": "<workspace>",
"at": "main:Catalog.Валюты.Form.ФормаЭлемента"
}
}
}
```
### Спуск по ветви
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "unica.view",
"arguments": {
"cwd": "<workspace>",
"at": "main:Catalog.Валюты.Form.ФормаЭлемента.Item"
}
}
}
```
## Что где лежит
| Вопрос | Адрес |
|--------|-------|
| Состав формы | `<объект>.Form.<Форма>` → ветви `Item`, `Attribute`, `Event`, `Module` |
| Права роли | `Role.<Роль>` → ветвь `Right`, объект права в `props` со счётчиками |
| Схема компоновки | `<объект>.Template.<Макет>` → `DataSet` → набор → `Field`, `Query`; варианты настроек — `Setting` |
| Табличный макет | `<объект>.Template.<Макет>` → `Area` → область → `Body` (непустой текст) и `Parameter` |
| Пакет XDTO | `XDTOPackage.<Пакет>` → `Namespace`, `Type`, `Property` |
| Подсистема | `Subsystem.<Имя>` → `Interface` → `Command` |
| Методы модуля | `<объект>.Module.<Роль>` → `Method`, `Region`, `Event`, `Body` |
Поддержка поставщика приходит в `props.support` объекта — читай её перед любой
правкой объекта на замке и решай через release-support, а не правкой напрямую.
## Страницы
`limit` ограничивает страницу коллекции, ответ возвращает `cursor`. Курсор
непрозрачен и привязан к тому же вопросу: тот же адрес, представление и `limit`. Страницы продолжают сохранённый
результат, даже если исходники уже изменились. Чужой, поддельный или истёкший
курсор отклоняется кодом `invalid_cursor` —
начинай обход заново, а не подставляй курсор от другого вызова.
## Словарь операций
Ответ `unica.view` узла несёт `can` — операции, которые `unica.apply` примет
на этом узле: имя `op`, ожидаемый ключ `args` и признак `implemented`. Состав
зависит от вида узла и дерева, которому он принадлежит: реквизит объекта
и реквизит формы, параметр СКД и параметр веб-сервиса получают разные
операции. Подробный контракт аргументов одной операции читается адресом
`<узел>.Can.<операция>`: имя операции занимает остаток адреса вместе с точкой
(`main:Catalog.Валюты.Can.attribute.add`). Неизвестная операция или операция
не того узла отклоняется `bad_value`, а `next` ведёт к словарю узла. Если
`apply` отвечает, что операция здесь не применима, его `next` ведёт к узлу,
где она исполнима.
Фильтра у `unica.view` и `unica.diff` нет: предмет вопроса задаёт адрес.
Коллекция читается адресом ветви страницами через `limit`, сравнение части
узла — `unica.diff` по адресам этой части. Аргумент `filter` отклоняется
`bad_value`, и `next` называет адрес, который его заменил.
## Отказы
| Код | Что случилось |
|-----|---------------|
| `bad_value` | адрес без префикса набора, лишний аргумент вроде `filter`, либо операция `Can.<op>` неизвестна или не применима к узлу |
| `provider_unavailable` | набор исходников не допущен рабочим пространством |
| `not_found` | объект не зарегистрирован в конфигурации, либо адрес не существует в профиле платформы |
| `invalid_cursor` | курсор чужой, просроченный или от другого вопроса |
## Правка
Чтение и правка разделены. Изменения вносит `unica.apply`; для BSL это
операции `code.insert` и `code.replace`.
**Селектор — это адрес.** Отдельного поля с методом или якорем нет: что
править, называет `args.at`. Узел метода — `…Module.<Роль>.Method.<Имя>`,
тело модуля целиком — `…Module.<Роль>.Body`. Правится выбранный участок, а не
модуль целиком, поэтому подход годится и для модулей, которые не поместились
бы в один запрос.
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "unica.apply",
"arguments": {
"at": "main:CommonModule.SourceAccessExample",
"ops": [
{
"op": "code.replace",
"args": {
"at": "main:CommonModule.SourceAccessExample.Method.BeforeReplacement.Body",
"text": "\t// новое тело"
}
}
]
}
}
}
```
Предпросмотр возвращает план и `data.executionToken`. Для исполнения передай
только `executionToken` с этим значением. Для другого адреса или операций
получи новый план. План сохраняет прочитанные входы и ожидаемые изменения;
изменение прочитанных байтов даёт `stale_revision`, а изменение файла вне входов плана
не мешает исполнению.
Токен относится к сохранённому плану этого workspace и текущего демона.
После истечения срока токена или перезапуска демона получи новый план.
Токен не заменяет поручение пользователя внести правку.