Source Access

---
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`.

## Адрес

```
<набор исходников>:<Вид>[.<Имя>[.<Ветвь>[.<Имя>...]]]
```

`main:Catalog.Валюты` — объект, `main:Catalog.Валюты.Form.ФормаЭлемента` — его
форма, `main:Catalog.Валюты.Module.Object.Method.ПередЗаписью` — метод модуля
объекта. Вид цели задаёт число сегментов: прикладное имя, совпадающее с
названием вида, объект в ветвь не превращает.

Префикс набора обязателен. Адрес без него отклоняется кодом `bad_value` с
подсказкой вызвать `unica.view {}`.

## Порядок работы

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` |
| Пакет XDTO | `XDTOPackage.<Пакет>` → `Namespace`, `Type`, `Property` |
| Подсистема | `Subsystem.<Имя>` → `Interface` → `Command` |
| Методы модуля | `<объект>.Module.<Роль>` → `Method`, `Region`, `Event`, `Body` |

Поддержка поставщика приходит в `props.support` объекта — читай её перед любой
правкой объекта на замке и решай через release-support, а не правкой напрямую.

## Страницы

`limit` ограничивает страницу коллекции, ответ возвращает `cursor`. Курсор
непрозрачен и привязан к тому же вопросу: тот же адрес, представление, фильтр и `limit`. Страницы продолжают сохранённый
результат, даже если исходники уже изменились. Чужой, поддельный или истёкший
курсор отклоняется кодом `invalid_cursor` —
начинай обход заново, а не подставляй курсор от другого вызова.

## Проекция модуля

`filter` осмыслен только для проекций модуля и только там, где он объявлен:

| Ключ | Где применим | Что делает |
|------|--------------|------------|
| `context` | `Body`, `Method` | оставляет ветку условной компиляции одного контекста: `client`, `server`, `externalConnection`, `thinClient`, `webClient` и прочие имена профиля |
| `public` | `Method` | оставляет только экспортные методы |

На любой другой проекции фильтр отклоняется кодом `bad_value` с названием
причины — это не молчаливое игнорирование.

## Отказы

| Код | Что случилось |
|-----|---------------|
| `bad_value` | адрес без префикса набора, либо фильтр не той формы или не на той проекции |
| `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 и текущего демона.
После истечения срока токена или перезапуска демона получи новый план.
Токен не заменяет поручение пользователя внести правку.