lekot/vscodepluginfor1cdev/agent-api

CDT 41 Agent API — Skill Reference

Расширение CDT 41 для VS Code предоставляет 100 runtime-команд Agent API для программного управления метаданными, Хранилищем конфигурации, фоновыми задачами, CFE-проектами, поддержкой конфигурации, привязками, раскаткой, отладкой, статическими формами и формами enterprise, СКД, XDTO-пакетами и внешними EPF/ERF 1С:Предприятие. Основной транспорт для агента — стандартный Streamable HTTP MCP; прямой вызов через vscode.commands.executeCommand и legacy /command остаются совместимыми.

MCP (Streamable HTTP) и discovery

Расширение поднимает локальный MCP endpoint на случайном порту при активации. Координаты записываются в discovery-файл:

<workspaceFolder>/.vscode/cdt-agent-bridge.json

Формат:

{
  "schemaVersion": 2,
  "instanceId": "7ef1b2b7-...",
  "port": 63088,
  "token": "baf0b38e...hex64...",
  "pid": 42144,
  "workspaceFolder": "C:/workspaces/my-configuration",
  "createdAt": "<ISO-8601 activation time>",
  "extensionVersion": "<installed extension version>",
  "docs": "https://github.com/lekot/VScodePluginFor1CDev/blob/main/docs/features/agent-api/agent-skill.md",
  "quickstart": "POST http://127.0.0.1:<port>/command ...",
  "mcp": {
    "url": "http://127.0.0.1:63088/mcp",
    "transport": "streamable-http",
    "authorization": "bearer"
  },
  "helperScriptPath": "<extensionPath>/resources/agent-bridge/call.sh",
  "discoverScriptPath": "<extensionPath>/resources/agent-bridge/discover.sh"
}

Поля helperScriptPath / discoverScriptPath относятся к legacy /command и сохранены для совместимости.

schemaVersion: 2 добавляет стандартный MCP endpoint, не удаляя ни одного legacy-поля. Discovery записывается атомарно; клиент должен перечитывать его после каждой активации расширения, потому что порт и token меняются. Token передаётся только в заголовке и не должен добавляться к URL или попадать в логи.

Подключение MCP

Подключите MCP-клиент к mcp.url и настройте заголовок Authorization: Bearer <token> из того же discovery-файла. Endpoint принимает POST, GET и DELETE, использует stateful sessions и отклоняет запросы без token, не с loopback-интерфейса либо с посторонним Host/Origin.

По умолчанию MCP публикует семь компактных tools. Шесть диспетчеров покрывают все 100 операций Agent API по статическим профилям; cdt_catalog перечисляет операции и выдаёт схему по запросу.

Шесть диспетчеров принимают { operation, arguments }: operation — прежнее имя cdt_* из каталога, arguments — прежний input Agent-команды. cdt_catalog({}) возвращает 100 имён, краткие описания и профили; cdt_catalog({ operation: "cdt_debug_get_variables" }) возвращает JSON Schema одной операции. Все аргументы строго валидируются прежними Zod-схемами до вызова Agent-команды; невоплотимые в JSON Schema refinements остаются runtime-проверками. Полный нормативный mapping и annotations находятся в MCP specification.

Например, чтение списка конфигураций вызывается как cdt_read({ operation: "cdt_list_configurations", arguments: {} }). Установка прав вызывается через cdt_write({ operation: "cdt_roles_set_rights", arguments: { roleName: "Менеджер", objects: ["Catalog.Товары: @view"] } }).

Если процесс расширения запущен с CDT_MCP_LEGACY_TOOLS=1, к семи compact tools дополнительно регистрируются 100 индивидуальных имён операций с исходными схемами. Без этой переменной по умолчанию доступны только семь инструментов. Прямые Agent-команды и legacy /command сохраняют прежние идентификаторы и поведение.

Каждый вызов диспетчера выполняет ровно одну существующую Agent-команду и возвращает исходный AgentResult в structuredContent и JSON-копией в text content. Входные объекты строгие: неизвестные поля запрещены. Mutating tools сохраняют очереди Agent API.

Фоновые задачи

Длительные deploy, deploy выбранных/изменённых файлов, pull, export status, EPF/ERF operations, команды СКД (compile, info, edit, validate), операции поддержки конфигурации (setObjectMode, enableObjectRules, sync, verify), операции TestClient launch, start, shot, native и debug-команды start, startFromBinding, waitForStop можно запустить с background: true. MCP-схемы для этих операций по умолчанию выбирают background; синхронный MCP-вызов задаёт background: false. Прямые Agent-вызовы этих операций сохраняют синхронное поведение без background; мутации Хранилища остаются фоновыми по умолчанию и принимают background: false для синхронного вызова.

Передайте taskId из receipt в 1c-metadata-tree.agent.task.status, .task.result или .task.cancel. В compact MCP это операции диспетчера cdt_read, например cdt_read({ operation: "cdt_task_status", arguments: { taskId } }) и cdt_read({ operation: "cdt_task_result", arguments: { taskId } }); это не отдельные tools по умолчанию. Receipt немедленно возвращает status: "working"; task snapshots сообщают running, completed, failed или подтверждённый cancelled, флаг cancellationRequested и elapsedMs. Для running задачи время растёт от момента создания; после terminal state elapsedMs фиксируется. recentMessages содержит этапы операции и доступные свежие строки процесса. Tail содержит не более 24 сообщений по 320 символов и проходит credential-pattern redaction до сохранения. task.result после завершения добавляет исходный AgentResult без потери его typed data. Терминальные результаты хранятся 15 минут; running задачи не вытесняются лимитом памяти. task.cancel только запрашивает отмену: receipt остаётся working, а snapshot сохраняет running, пока нижележащая операция не вернёт фактический результат. Для Хранилища inDoubt и acknowledged сохраняются даже после запроса отмены.

CFE project lifecycle

cfe.listProjects, cfe.getContext и cfe.validate читают устойчивые связи из .vscode/cfe-projects.json. cfe.createProject принимает baseConfigurationId, имя расширения, назначение, префикс и режим совместимости; необязательный target допускается только как путь внутри workspace без абсолютных путей и переходов ... cfe.borrowObject принимает extensionConfigurationId и ровно один источник: sourceDotPath (Type.Name) либо sourceUuid. Заимствование идемпотентно по UUID, выполняется только из связанной основной конфигурации и пока поддерживает Catalog, Document, Enum и CommonModule; неподтверждённые замыкания зависимостей отклоняются с CFE_DEPENDENCY_UNSUPPORTED.

cfe.createInterceptor принимает UUID уже заимствованного объекта, moduleKind из Module|ObjectModule|ManagerModule|RecordSetModule|ValueManagerModule, имя метода и kind before|after|instead|changeAndValidate. Module kind сверяется с типом объекта; before/after для функций запрещены. Для changeAndValidate обязателен SHA-256 expectedSourceHash канонического текста исходного метода. Результат содержит created|already-exists, имя перехватчика, source hash и относительный module path; конфликт пользовательского тела даёт CFE_INTERCEPTOR_CONFLICT, drift — CFE_SOURCE_CHANGED.

cfe.createOwnForm создаёт managed-форму у существующего CFE Catalog/Document по ownerDotPath; имя должно соответствовать NamePrefix. cfe.borrowForm принимает UUID уже заимствованного владельца и ровно один selector sourceFormUuid|sourceFormName; результат borrowed|already-borrowed содержит относительные metadata/form/module paths. Владелец и его зависимости никогда не заимствуются автоматически.

cfe.extendForm принимает UUID заимствованной формы, SHA-256 expectedFormHash исходного Ext/Form.xml и непустой список аддитивных операций: addAttribute, addCommand, addElement, setFormEvent, setElementEvent, addCommandAction. Допустимые callType — Before|After|Override; новые visual elements — UsualGroup|InputField|Button. BaseForm не удаляется и не перезаписывается, идентичное повторное изменение возвращает unchanged.

Для всех form-операций closure fail-closed: Catalog, Document, Enum/EnumValue, CommonPicture и StyleItem должны быть уже заимствованы и совпадать с объектом основной конфигурации. Неизвестная metadata reference, отсутствующая или незаимствованная зависимость возвращает CFE_DEPENDENCY_UNSUPPORTED до записи. Обычный Form editor не сохраняет и не создаёт handlers для заимствованной формы — используйте cfe.extendForm (CFE_ADOPTED_OPERATION_REQUIRED). Ответы содержат JSON-safe DTO: идентификаторы конфигураций и метаданные связи, но не сессии VS Code и не абсолютные пути. Создание и заимствование обновляют discovery конфигураций и дерево метаданных.

Доверие и опасные операции

Bearer даёт аутентифицированному локальному MCP-клиенту ту же authority, что legacy /command, то есть доступ ко всему Agent API. В частности:

• операция cdt_debug_evaluate исполняет BSL-выражение, которое может иметь side effects;
• deploy/pull меняют информационные базы или workspace;
• support set/enable/sync меняют master-файл и могут запускать Configurator для связанных ИБ;
• support verify не меняет master или информационные базы, но запускает внешние Configurator dump-процессы и записывает durable audit run в локальный журнал;
• cdt_dump_external_processor и cdt_build_external_processor запускают Configurator и создают файлы; standalone может потерять ссылочные типы и требует явного acknowledgeTypeLoss: true;
• debug/forms/SKD запускают и останавливают дочерние процессы; SKD принимает локальные input/output paths;
• XDTO export с outputPath, import/create/merge и metadata tools изменяют файлы конфигурации.

Подключайте только доверенный локальный MCP-клиент и не передавайте token в URL или логи. MCP annotations описывают риск, но не являются дополнительной авторизацией. Отмена запроса до dispatch не запускает Agent-команду; отмена после dispatch не прерывает уже запущенный процесс или мутацию, а только отбрасывает итоговый результат.

Legacy POST /command, helper-скрипты и все Agent-команды продолжают работать по прежнему контракту.

Legacy /command

• Health check: GET /health → { "ok": true, "pid": ... }
• Команда: POST /command с JSON-телом { "name": "...", "args": { ... } }
• Аутентификация: заголовок Authorization: Bearer <token>
• Content-Type: application/json; charset=utf-8 (важно для кириллицы)

Пример вызова через curl:

curl -X POST "http://127.0.0.1:$PORT/command" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"name":"1c-metadata-tree.agent.listObjects","args":{"type":"Catalog"}}'

Пример вызова через Node.js (корректная кодировка для кириллицы):

const data = JSON.stringify({
  name: '1c-metadata-tree.agent.debug.evaluate',
  args: { sessionId, frameId: 1, expression: 'Сумма' }
});
const req = http.request({
  hostname: '127.0.0.1', port: PORT, path: '/command', method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': Buffer.byteLength(data)
  }
}, res => { /* ... */ });
req.end(data);

Whitelist команд

Через bridge доступны только команды, соответствующие паттерну:

/^1c-metadata-tree\.agent(?:(?:\.debug|\.forms|\.skd|\.xdto)?\.[a-zA-Z]+|\.roles\.setRights)$/

Вызов через helper-скрипт