Руководство по подключению Agent и MCP к OT Flash
Протокол, авторизация, контракты инструментов и полный процесс вызова
Создавайте отслеживаемые приложения для данных и знаний с использованием публичного Remote MCP OT Flash r56. В этом руководстве описаны OAuth, сообщения протокола, справочник параметров всех объявленных инструментов, правила доказательств, условные возможности и процессы восстановления, а также готовый к запуску клиент и примеры на синтетических данных.
Разработчики Agent, инженеры по интеграции и администраторы
В прилагаемых примерах названия отображаемых полей сохранены на китайском языке. Перевод языка интерфейса и пояснительного текста не изменяет фактические имена таблиц, столбцов, значения перечислений, названия инструментов или поля протокола.
Содержание
- 1Область подключения Agent и критерии завершения
- 2Быстрое подключение и обнаружение возможностей
- 3Обнаружение, регистрация и авторизация OAuth
- 4Scope, границы ресурсов и права в реальном времени
- 5Сообщения HTTP и современного MCP
- 6Совместимость со старыми клиентами протокола
- 7Выбор правильного инструмента и канала доказательств
- 8Ресурсы онтологии и типы ID
- 9Контракт табличных запросов и структуры Doris
- 10Многомерный Top3 и обработка усечения
- 11Поиск в знаниях: полный исходный текст и пригодность доказательств
- 12Нативная модель Search и сеансы
- 13Соглашения по языку и регионам
- 14Объединённый анализ и интерактивные результаты
- 15Постоянные визуальные отчёты и MCP Apps
- 16Черновики артефактов, предпросмотр, планы и применение
- 17Контракты создания кандидатов онтологии и публикации
- 18Опубликованные модели: запрос кандидатов и замыкание ссылок
- 19Делегирование задач агенту онтологии
- 20Business Workspace MCP
- 21Ввод бизнес-знаний и вопросы на подтверждение
- 22Ответы, ошибки и безопасные повторные попытки
- 23Безопасность интеграции и границы возможностей
- 24Настройка администратором и условные переключатели
- 25Готовый к запуску клиент и примеры вызовов
- 26Встраивание интерфейса диалога онтологии
- 27Чек-лист приёмочной проверки интеграции
- 28Нормативные ресурсы и сопровождение
- 29Справочник параметров инструментов: базовые инструменты и нативный Search
- 30Справочник параметров инструментов: таблицы, граф и знания
- 31Справочник параметров инструментов: анализ и отчёты
- 32Справочник параметров инструментов: моделирование и исходные задачи
- 33Справочник параметров инструментов: ввод знаний и бизнес-области
- 34Справочник параметров инструментов: Business Workspace
Область подключения Agent и критерии завершения
Выберите точку входа авторизации и на основе квитанций сервера выполняйте запросы, сбор доказательств или контролируемую запись.
OT Flash r56 предоставляет внешним Agent через Remote MCP возможности работы с данными и знаниями в рамках онтологии, а также отдельную точку входа в Business Workspace. Agent должен определять, какие операции ему доступны, по фактическим tools/list, inputSchema, scope OAuth и текущим правам на ресурсы; по статическому руководству нельзя заключать, что в развёртывании включены все необязательные функции.
| Вход | Назначение | Границы |
|---|---|---|
| /mcp | Онтология, таблицы данных, документные знания, нативный Search и условно открытые анализ и моделирование | Пересечение текущих прав пользователя и ресурсов, выбранных при данной авторизации |
| /mcp/business | Обнаружение бизнес-систем, запросы, планы действий, состояние и выполнение | Отдельная авторизация бизнес-систем и опубликованные контракты |
| Страница встраивания агента онтологии | Диалог с онтологией в интерфейсе для пользователя-человека | Требует реального сеанса входа; это не точка обмена на MCP Token без входа в систему |
Классификация возможностей
- Базовое чтение: онтология и ресурсы, позиционирование на графе, поиск знаний и полный исходный текст, детали авторизованных таблиц и Doris SQL.
- Отдельное делегирование: dfc_search требует search:operate, при этом по-прежнему действуют права исходного пользователя и модели.
- Условно открытые: анализ, постоянные отчёты, черновики артефактов и их применение, запросы моделей онтологии и делегированные задачи Agent.
- Недоступные возможности: dfc_etl для Flash только сообщает capabilities и не предоставляет выполнение Heavy ETL. AutoML и внутренние точки входа рабочих пространств FocusCode не входят в публичный Flash API этого руководства.
Критерии завершения
Для чтения фактов нужна квитанция реально выполненного запроса или полного исходного текста; при генерации кандидатов необходимо указать, что они ещё не применены; публикацию подтверждает только реальная квитанция APPLIED; при отмене нужно различать запрос отмены и её подтверждение. Ни текст ответа, ни HTTP 200, ни принятие вызова инструментом, ни заявление модели «выполнено» сами по себе не доказывают успех бизнес-операции.
Прилагаемый reference/mcp-tool-catalog.json — это офлайн-справочник объявленных инструментов r56; он содержит и условно включаемые определения и не является актуальным tools/list какого-либо пользователя. Полный каталог включает 28 основных инструментов онтологии, 4 условных расширения контроллеров и 8 бизнес-инструментов; это не означает, что всё открыто по умолчанию.
Быстрое подключение и обнаружение возможностей
Начните с официального домена экземпляра и с минимальными правами определите фактически доступные инструменты.
- Получите у администратора официальный корневой адрес HTTPS и онтологию или бизнес-систему, к которым требуется доступ. Не используйте примеры доменов из документации для реальных бизнес-вызовов.
- Настройте адрес сервера MCP как https://flash.example.com/mcp; Business Workspace использует /mcp/business того же домена.
- Запустите вход и авторизацию OAuth так, как это поддерживает клиент, проверьте ресурсы и scope; не передавайте имя пользователя и пароль в MCP.
- Используйте обнаружение или инициализацию протокола соответствующего поколения, затем прочитайте tools/list и описания ресурсов.
- Сначала выполните небольшой запрос только для чтения, проверьте структурированные результаты и ошибки, и только затем выполняйте задачу пользователя.
Фрагмент конфигурации клиента
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Этот фрагмент показывает, как задаётся адрес сервера; конкретная структура файла конфигурации и поддержка OAuth зависят от клиента. Не указывайте в публичных файлах реальные access_token, refresh_token, Cookie или пароли администратора.
Обнаружение современного протокола
POST /mcp HTTP/1.1
Host: flash.example.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}Проверки перед подключением
- Корневой адрес ресурса, issuer OAuth и внешний адрес обратного прокси совпадают.
- Клиент поддерживает соответствующее поколение протокола, а не отправляет безусловно initialize на точку входа нового протокола.
- Текущая авторизация привязана к требуемой онтологии или бизнес-системе.
- Token действителен, и новые необязательные scope явно авторизованы.
Обнаружение, регистрация и авторизация OAuth
Используйте код авторизации и PKCE и не раскрывайте Agent учётные данные для входа в продукт.
| Конечная точка | Метод | Назначение |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Обнаружение MCP-ресурса онтологии |
| /.well-known/oauth-protected-resource/mcp | GET | Обнаружение по пути ресурса онтологии (для совместимости) |
| /.well-known/oauth-protected-resource/mcp/business | GET | Обнаружение бизнес-ресурса MCP |
| /.well-known/oauth-authorization-server | GET | Метаданные сервера авторизации |
| /oauth/register | POST JSON | Динамическая регистрация public client |
| /oauth/authorize | GET или form POST | Вход, выбор ресурса и подтверждение авторизации |
| /oauth/token | POST form | Обмен кода авторизации и обновление с ротацией |
| /oauth/revoke | POST form | Отзыв Token |
| /oauth/grants | GET | Просмотр авторизованных подключений вошедшим пользователем |
| /oauth/grants/revoke | POST form | Отзыв подключения по сценарию исходной страницы |
Порядок авторизации
- Прочитайте метаданные защищённого ресурса и сервера авторизации. Ответ 401 на запрос без Token и заголовок WWW-Authenticate указывают на адрес обнаружения ресурса.
- Зарегистрируйте клиент или используйте существующую идентификацию клиента. В r56 при динамической регистрации public client используется token_endpoint_auth_method=none; нельзя заменять PKCE клиентским секретом.
- Сгенерируйте случайные state и code_verifier, вычислите code_challenge S256.
- Откройте адрес authorize, указанный в метаданных, передав response_type=code, client_id, точный redirect_uri, scope, resource, state, code_challenge и code_challenge_method=S256.
- Пользователь входит в DataFocus и выбирает онтологию или бизнес-систему. Клиент не может заранее выбрать ресурсы, к которым у пользователя нет доступа.
- Примите обратный вызов, проверьте state и issuer; обменяйте код авторизации, используя исходный code_verifier.
- Используйте access_token только для Bearer-аутентификации MCP. Для обновления используйте исходный процесс OAuth; надёжно сохраняйте полученный после ротации refresh_token.
Пример регистрации
{
"client_name": "OT Flash Knowledge Client",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"application_type": "native",
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}Обратный вызов веб-клиента использует HTTPS; нативные клиенты могут использовать поддерживаемые loopback-адреса. При авторизации и обмене на Token обратный вызов должен точно совпадать с зарегистрированным. Один Grant относится к одному protected resource; не смешивайте scope онтологии и Business Workspace в одном подключении.
Жизненный цикл Token
По умолчанию на сервере r56 access token — 3600 секунд, refresh token — 2592000 секунд, код авторизации — 300 секунд; развёртывание может переопределить эти значения. Клиент должен ориентироваться на expires_in из ответа token и на фактические ошибки, не зашивая значения по умолчанию в код. После обновления замените сохранённый Token; отзыв роли, прав на ресурс или Grant приводит к отклонению последующих вызовов.
Scope, границы ресурсов и права в реальном времени
Авторизованный scope лишь делегирует существующие права: он не повышает роль и не делает бизнес-состояние общим для разных Grant.
| Scope | Типичные возможности | Важные ограничения |
|---|---|---|
| ontology.metadata:read | Онтология, ресурсы, структура таблиц | Онтология и таблицы должны входить в авторизацию и быть доступны для чтения в данный момент |
| ontology.graph:read | Поиск по графу и соседи | Возвращается информация о позиционировании, а не доказательства фактов |
| ontology.knowledge:read | Позиционирование знаний и полный исходный текст | Сохраняются исходные права баз знаний и документов |
| ontology.table:query | SQL-запросы к таблицам онтологии и запросы к опубликованным моделям | Для запроса таблицы также нужен scope metadata; действуют фактические источники и права на столбцы |
| search:operate | Нативные модели по ключевым словам и сеансы | Отдельное явное делегирование; выполняется с исходными правами модели и правами пользователя на таблицы и столбцы |
| etl:operate | Flash ETL capabilities | Heavy ETL недоступен |
| authoring.contract:read | Условно открытые контракты моделирования | Также требуются переключатели функций и соответствующие ресурсы |
| authoring.artifact:read | Чтение кандидатов, планов и т. п. в рамках текущей авторизации | Привязано к исходному субъекту, Grant и ресурсам |
| authoring.artifact:draft | Отправка кандидатов, предпросмотр и т. д. | Не авторизует выполнение или публикацию |
| authoring.artifact:apply | Контролируемые планы и применение | По-прежнему требуются исходные бизнес-роли, политики и утверждения |
| execution.script:draft | Черновики определённых скриптов | Не авторизует фактическое выполнение скриптов |
| datasource.http:read / draft / test / import | Условно открытые возможности артефактов источников данных HTTP | Для каждой — отдельный переключатель и исходные права |
Требования к комбинациям чтения
dfc_table detail требует ontology.metadata:read; query дополнительно требует ontology.table:query. dfc_ontology_query требует двух scope чтения: graph и knowledge. dfc_knowledge_search/detail требует knowledge. published_model/published_query используют table:query; candidate_query дополнительно требует authoring.artifact:read. Инструменты анализа также проверяют разрешённые scope доказательств; постоянные отчёты требуют metadata и table query.
Не зашивайте авторизацию по умолчанию
Набор scope онтологии по умолчанию для r56 включает table query; Search и ETL требуют явного делегирования. Окончательным критерием остаются метаданные обнаружения, страница авторизации, фактический scope Token и tools/list. Утверждения из старой документации о том, что «у онтологии по умолчанию заведомо нет SQL» или «только шесть инструментов», не отражают текущую реализацию.
Изоляция состояний
Сеансы, отчёты, кандидаты и планы действий имеют собственных владельцев и области действия. Обновление access token не передаёт работу исходного Grant другому Grant. Не объединяйте с текущим подключением sessionId, reportId, planId, токены утверждений или Token источников, возвращённые другим подключением.
Сообщения HTTP и современного MCP
Правильно отправляйте метаданные по каждому запросу и соответствующие заголовки маршрутизации; раздельно обрабатывайте HTTP и результаты инструментов.
| Параметр | Поведение r56 |
|---|---|
| Транспорт | Stateless Streamable HTTP, POST JSON-RPC |
| Поддерживаемые идентификаторы версий | 2026-07-28, а также 2025-11-25, 2025-06-18, 2025-03-26 |
| Современные методы | server/discover, tools/list, tools/call, resources/list, resources/read — открываются по фактическим возможностям |
| Заголовок сеанса | Mcp-Session-Id не назначается |
| GET и DELETE | /mcp и /mcp/business возвращают 405 |
| Серверные уведомления SSE | Не предоставляются этими двумя публичными точками входа MCP |
| Кэширование каталога | Ответы современного обнаружения и списков содержат ttlMs=60000 и cacheScope=private |
| Обычный результат | Современный результат содержит resultType=complete и метаданные идентификации сервиса |
Содержимое, которое должно совпадать
- MCP-Protocol-Version совпадает с io.modelcontextprotocol/protocolVersion в params._meta.
- Mcp-Method совпадает с методом JSON-RPC.
- Mcp-Name для tools/call совпадает с params.name; заголовок имени для resources/read совпадает с URI.
- Каждый современный запрос содержит объект io.modelcontextprotocol/clientCapabilities; также передаётся стандартный clientInfo для идентификации клиента.
Пример вызова
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "dfc_ontologies",
"arguments": {"page": 1, "pageSize": 20},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}Соответствующие заголовки для HTTP: Mcp-Method: tools/call и Mcp-Name: dfc_ontologies. Все ACCESS_TOKEN в примерах являются заполнителями. Не помещайте Bearer Token в URL, в параметры JSON или в ключи кэша.
Чтение результата
Сначала обработайте статус HTTP, затем проверьте JSON-RPC error; при наличии result продолжите проверку isError. Успешный результат инструмента обычно предоставляет structuredContent, а также text-содержимое с тем же бизнес-JSON; отдавайте приоритет структурированному каналу и не учитывайте text и structuredContent дважды как два независимых набора фактов. HTTP 200 может содержать ошибку инструмента.
Публичные ресурсы и UI
Встроенный ресурс с инструкциями не зависит от MCP Apps. При этом точке входа Business Workspace ресурс с описанием онтологии не предоставляется. Клиенты с поддержкой визуализации должны обнаруживать соответствующий UI через фактически объявленные возможности и tool _meta и не угадывать URI ресурсов, которые не были возвращены.
Совместимость со старыми клиентами протокола
В клиентах, которые всё ещё используют рукопожатие инициализации, придерживайтесь одного поколения протокола.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Отправьте initialize и прочитайте согласованные сервером версию протокола и capabilities.
- Отправьте необходимые уведомления о завершении инициализации в соответствии с протоколом клиента; уведомления не возвращают обычных результатов инструментов.
- Используйте tools/list для чтения текущих авторизованных инструментов, затем отправьте tools/call.
- Заголовки и сообщения должны соответствовать поколению протокола текущего запроса; не применяйте к сообщениям 2026-07-28 старые процедуры initialize или ping.
Старый протокол использует те же Bearer/OAuth, разрешения и контракты инструментов. Это не означает, что сервер обязательно предоставляет долгоживущие SSE-соединения старого типа или Mcp-Session-Id; публичная служба r56 остаётся без сохранения состояния.
Ошибки протокола
| Ситуация | Типичный результат | Как исправить |
|---|---|---|
| Несоответствие современных заголовков и сообщения | HTTP 400 JSON-RPC -32020 | Исправьте заголовки, метаданные и имя инструмента |
| Неподдерживаемая версия | -32022 со списком поддерживаемых версий | Выберите фактически поддерживаемый протокол |
| Неизвестный метод | JSON-RPC -32601; современный запрос может вернуть HTTP 404 | Проверьте поколение протокола и метод |
| Отсутствующие или недопустимые параметры | JSON-RPC: ошибка параметров или isError инструмента | Исправьте в соответствии с фактическим inputSchema |
Выбор правильного инструмента и канала доказательств
Выбирайте маршрут по нерешённому бизнес-вопросу и не повторяйте сбор доказательств по фиксированной цепочке вызовов.
| Задача | Предпочтительный инструмент | Необходимые доказательства для завершения |
|---|---|---|
| Обнаружение авторизованных тем и ресурсов | dfc_ontologies dfc_ontology_resources | Фактические типы ID ресурсов и текущая область видимости |
| Табличная статистика и TopN | dfc_table query | Квитанция успешного выполнения и полные evidenceRows |
| Поиск регламента, контракта или отчёта | dfc_ontology_query или knowledge search/detail | Полный, авторизованный исходный текст, пригодный для использования в качестве факта |
| Поиск объекта в графе | dfc_ontology_graph search/neighbors | Сначала найдите фактический источник, после этого получите соответствующий факт |
| Нативное взаимодействие по ключевым словам | dfc_manual, затем dfc_search | Фактические результаты в исходной модели и бизнес-фреймах |
| Объединённый анализ и отчёты | dfc_analysis_* или dfc_report_* | Реальные статусы каждого структурированной ветви и документальных доказательств |
| Изменение представления или модели онтологии | dfc_authoring_* и инструменты артефактов | Отдельно проверяйте кандидатов, планы, утверждения и фактическое применение |
| Выполнение бизнес-команд | dfb_* для /mcp/business | Опубликованный контракт и квитанция исходного ActionPlan |
Как избежать лишних вызовов
Если уже есть актуальная, полная, авторизованная структура таблицы, не требуйте повторного detail при каждом запросе; если уже есть надёжные результаты позиционирования и доказательства, не повторяйте тот же поиск. При нехватке какого-либо измерения выполняйте ограниченный дополнительный запрос. Если ошибка явно не подлежит повтору, сначала устраните недостающее звено, а не подменяйте анализ ситуации повторной попыткой.
Исключения для Flash
dfc_etl capabilities может возвращать available=false и ETL_NOT_INCLUDED_IN_OT_FLASH. Статические описания встроенных функций ETL служат межпродуктовым справочным материалом и не доказывают, что во Flash установлен ETL; они также не позволяют Agent автоматически переходить для выполнения на Heavy или к другому арендатору.
Ресурсы онтологии и типы ID
Сначала получите фактические координаты ресурса, чтобы не смешивать имена в хранилище, ID документов и ID базы знаний.
- Вызовите dfc_ontologies и просмотрите с помощью page и pageSize онтологии, авторизованные в этот раз и всё ещё доступные для чтения.
- Вызовите dfc_ontology_resources с реальным ontologyId; при необходимости выберите tables, answers, pinboards, documents и knowledgeBindings.
- Обрабатывайте пагинацию отдельно для каждого типа ресурса. Максимум для pageSize — 100; не судите обо всём наборе ресурсов по первой странице.
- Сохраните заявленный тип ресурса и исходный ID и используйте их в последующих вызовах без изменений.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Координаты | Источник | Чем нельзя заменить |
|---|---|---|
| ontologyId | Список авторизованных онтологий или текущий действующий контекст | ID другой онтологии |
| ID табличного ресурса | Список tables или надёжный контекст | physicalName или отображаемое имя таблицы |
| tblDisplayName colDisplayName | Метаданные текущей таблицы и столбцов | Угаданный физический идентификатор SQL |
| knowledgeId | knowledgeBindings или фактическая квитанция поиска знаний | ID документного ресурса |
| assetId documentId chunkId evidenceId | Одна и та же фактическая квитанция позиционирования | Поля, собранные из разных результатов позиционирования |
| rid revisionId releaseId | Опубликованная модель или серверный контекст кандидата | Самостоятельно сгенерированный ID или latest |
Соглашения о точности
Все 64-битные идентификаторы ресурсов предпочтительно передавать как десятичные строки, без преобразования через Number в JavaScript. Некоторые бизнес-схемы допускают string или integer, но это не означает, что целочисленной точностью можно пренебречь. Непрозрачные локаторы (opaque locator), UUID, хэши и одноразовые токены также сохраняются как есть.
Контракт табличных запросов и структуры Doris
Выполняйте к авторизованным таблицам SQL-запросы только на чтение, сохраняя семантику выходных данных, точность значений и полноту.
Чтение структуры
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}В detail используйте реальный ID табличного ресурса. Сверьте schemaComplete, tblDisplayName, colDisplayName в columns и авторитетный sqlDataType, а также возвращённый queryContract. dataType — лишь сопоставление для совместимости; физическое имя в хранилище не является именем таблицы для SQL.
Выполнение запроса
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}Ограничения SQL
- Используйте отображаемые имена таблиц и столбцов, заключая идентификаторы в двойные кавычки. Запрос должен быть одним запросом Doris только на чтение в пределах онтологии.
- Явно перечисляйте выводимые столбцы; SELECT * и table.* запрещены: через физические столбцы нельзя обходить зарегистрированные права доступа к столбцам.
- Для соединений используйте явный JOIN ... ON; NATURAL JOIN и JOIN USING будут отклонены.
- Допустимы корректные выражения только на чтение, такие как многомерные агрегации, CTE, оконные функции, CASE, COUNT(DISTINCT ...); если выражение не покрыто семантической проверкой, это ещё не означает общего запрета на его выполнение.
- Сначала выполните агрегацию, сортировку и ранжирование в SQL и только затем ограничивайте число строк результата. maxRows по умолчанию — 100, максимум — 200.
Даты и часовые пояса
| Тип или цель | Форма | Примечания |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) и CURRENT_DATE | Не считайте текстовый литерал значением типа даты |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) и CURRENT_TIMESTAMP | Сверьте часовой пояс источника и часовой пояс сеанса |
| Относительное время | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Для дат и временных меток используйте соответствующие текущие функции |
| Группировка по времени | YEAR(column) или DATE_TRUNC(column, 'month') | Каждому выходному столбцу присваивайте уникальный псевдоним; ориентируйтесь на queryContract |
DATE('now', ...) в SQLite — это не контракт дат Doris для данного входа. Не переносите в рабочий SQL способ офлайн-проверки на SQLite из примеров документации.
Чтение квитанции запроса v8
evidenceRows — единственный канал, по которому Agent получает построчные данные; raw data для Agent недоступны. Числа в SQL кодируются как точные десятичные строки JSON; их числовой и бизнес-тип определяйте по resultColumnContracts, и их не следует интерпретировать как VARCHAR только потому, что в JSON значение передаётся строкой. Читайте executionReceipt, информацию о полноте и усечении, сохраняя сведения об источнике, такие как evidenceRowsSha256.
Выходные данные запросов, для которых есть цитируемая квитанция выполнения, можно цитировать как есть; только семантика, проверенная на стороне сервера, может служить основанием для последующих детерминированных вторичных вычислений. Нельзя по имени поля угадывать «накопленный остаток», «значение на конец периода», «币种» или самостоятельно добавлять единицы измерения. Пустой результат (ноль строк), сбой или усечение нельзя выдавать за полную статистику.
Многомерный Top3 и обработка усечения
Отвечайте на вопросы о ранжировании с помощью серверных агрегаций и оконных функций, не выполняя вторичных вычислений над неполными результатами.
Прилагаемый examples/top3.sql работает с примером таблицы: сначала выполняется агрегация по 区域, 类别 и 产品, затем внутри каждой комбинации 区域 и 类别 выполняется ROW_NUMBER, а при равных суммах для стабильного порядка используется название 产品. Запроса с maxRows=100 достаточно для 36 строк примера; для других бизнес-данных лимит нужно оценивать по фактическому числу групп.
- Получите фактическую структуру и текущую методику расчёта, уточните 币种, период, 订单状态 и правила обработки равных значений.
- Отправьте SQL с агрегацией и ранжированием на стороне сервера. Не запрашивайте сначала только итог по 区域, чтобы затем выдавать его за ранжирование 产品 внутри 类别.
- Проверьте контракт выходных столбцов и фактические evidenceRows, убедившись, что возвращённые данные покрывают все нужные группы.
- При обнаружении усечения выполняйте ограниченные секционированные запросы в пределах поддерживаемых сервером границ, например получая полный Top3 отдельно по каждому 区域; во всех запросах сохраняйте одну и ту же бизнес-методику расчёта.
- Если период в источнике изменился, выполните запрос заново и явно укажите новую версию; не смешивайте разные версии данных или устаревшие курсоры.
Восстановление после ошибок
TABLE_SCHEMA_INCOMPLETE означает, что нужно исправить запрос или получить полную структуру; сбои вроде ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID обрабатываются по возвращённым errorCode, retryable и remediation. Не утверждайте, что «все многомерные GROUP BY или оконные функции запрещены», и не выдумывайте ранжирование, не имея результатов запроса.
Поиск в знаниях: полный исходный текст и пригодность доказательств
Разделяйте позиционирование, чтение и цитирование фактов, сохраняя источник и полноту.
Два распространённых пути
| Путь | Назначение | Ключевые моменты |
|---|---|---|
| dfc_ontology_query | Поиск в привязанных к онтологии знаниях с возможной маршрутизацией по графу | Проверка полного canonical answerContextItems и пригодности доказательств |
| dfc_knowledge_search → фрагмент dfc_knowledge_detail | Явный поиск для позиционирования, затем чтение выбранного фрагмента | Предпросмотр поиска не является фактом; читайте полный исходный текст по тому же позиционированию |
{"name":"dfc_knowledge_search","arguments":{
"ontologyId":"<ONTOLOGY_ID>","query":"销售金额是否排除退货", "topK":5
}}
{"name":"dfc_knowledge_detail","arguments":{
"action":"chunk","ontologyId":"<ONTOLOGY_ID>",
"evidenceId":"<EVIDENCE_ID_FROM_THE_SAME_SEARCH_RESULT>"
}}Условия пригодности для фактов
- Проверьте текущий ACL, полноту содержимого и серверные canonicalFactEligible, citationEligible или соответствующий контракт выполнения.
- Полное содержимое привязано к contentSha256. Усечение, пропуск по бюджету или низкокачественное содержимое обрабатываются по фактическим полям.
- Метаданные документа, page_context, позиция в графе, поисковые сводки и предпросмотр не заменяют канонический исходный текст.
- В первую очередь копируйте evidenceId; когда требуются chunkId и documentId, они должны быть взяты из одного и того же результата позиционирования; не склеивайте и не придумывайте их.
Маршрутизация по графу
Результат search/neighbors — это информация о позиционировании. В query онтологии передавайте только объекты routeLocator, полностью возвращённые сервером, включая привязки, версии и поля подтверждения подлинности. Не упаковывайте самостоятельно assetId или knowledgeId в подобие выданного сервером locator и не передавайте обратно заявленные моделью подтверждения источника.
Восстановление структурированных документов
structuredPlan для dfc_ontology_query — это ограниченное восстановление с детерминированной проверкой, предназначенное специально для таблиц нестандартной структуры в документах. Используйте план, объявленный сервером, только после возврата текущего executionContractSha256, tableIndex, столбцов и полной таблицы. Обычные уже импортированные бизнес-таблицы должны обрабатываться через dfc_tableSQL; не используйте восстановление Markdown-таблиц как способ обойти авторизацию табличных запросов.
Стратегия поиска
knowledgeIds обычно опускается, чтобы охватить текущие включённые привязки; если параметр передаётся, используйте только реальные ID баз знаний из knowledgeBindings. Не указывайте ID ресурса документа как ID базы знаний. Для каждого нерешённого вопроса выполняйте новый ограниченный поиск и избегайте точных повторов, не дающих новых доказательств.
Нативная модель Search и сеансы
Используйте протокол ключевых слов Rust Search через dfc_search и дождитесь конечного состояния исходного бизнес-фрейма.
Сначала прочитайте описание, затем обнаруживайте возможности
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}Для dfc_search требуется явный search:operate. Инструмент служит обёрткой над исходным WebSocket-протоколом ключевых слов и не переписывает ключевые слова в запросы SQL или LLM. Сеанс привязан к текущему арендатору, пользователю, Grant, клиенту и модели; при каждой операции повторно проверяются исходные права на таблицы и столбцы.
Минимальная последовательность работы с сеансом
{"name":"dfc_search","arguments":{
"action":"model_create","data":{"tableIds":["<ACTUAL_TABLE_ID>"]}
}}
{"name":"dfc_search","arguments":{
"action":"open","data":{"sourceToken":"<MODEL_SOURCE_TOKEN>","language":"en-US"}
}}
{"name":"dfc_search","arguments":{
"action":"poll","data":{"sessionId":"<SEARCH_SESSION_ID>","waitMillis":10000}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"assist","datas":{}}}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"search","datas":{"search":"<QUERY_USING_ACTUAL_COLUMNS>","ambiguities":[]}}}
}}- model_create принимает от 1 до 100 реальных ID таблиц, на которые у пользователя есть права; либо model_read читает уже существующий собственный sourceToken.
- open возвращает только initializationSent; сначала выполните poll, прочитайте исходный бизнес-ответ init и подтвердите успех.
- Прочитайте assist и предложения, затем отправьте поддерживаемое исходное message. В query datas параметр isNl обёртка всегда задаёт равным false.
- Непрерывно читайте frames, различая предложения, разбор, приём и итоговый бизнес-результат.
- По завершении выполните close; при необходимости отмены — cancel и по фактическому состоянию задачи проверьте, остановлена ли она.
| action | data | Значение |
|---|---|---|
| capabilities | Не указывается или пустой объект | Чтение действий, команд, TTL и сведений о передаче |
| model_create | Массив tableIds | Создание модели, авторизованной для текущего пользователя |
| model_read | sourceToken | Чтение модели; столбцы без прав доступа и чувствительные настройки источников отфильтровываются |
| open | sourceToken и необязательный language | Создание нативного сеанса и отправка init |
| request | sessionId и message | Отправка исходного сообщения протокола type/datas |
| poll | sessionId и waitMillis от 0 до 30000 | Извлечение текущих буферизованных фреймов с возможным ограниченным ожиданием |
| cancel close | sessionId | Закрытие данного нативного сеанса; по нему нельзя судить о конечном состоянии BI |
Поддерживаемые исходные команды
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteРегистр команд и структура datas следуют текущим capabilities и протоколу исходного сеанса. Нельзя добавлять в request несуществующие действия; например, написание disambiguite должно сохраняться в точном соответствии с реальным протоколом. Максимальный размер сообщения — 256 Ki символов.
Сеансы и целостность
TTL сеанса — 10 минут; сеанс хранится, только пока жив текущий процесс, и его нельзя восстановить как долговременную задачу. Буфер вмещает не более 256 фреймов и ограничен лимитом памяти; при bufferOverflow=true уже извлечённые фреймы нельзя считать полным результатом. После ошибки передачи сначала выполните poll исходного сеанса и не отправляйте вслепую повторно запрос, который, возможно, уже выполнен.
Текущая обёртка не предоставляет сохранение ответов или дашбордов, чтение/запись истории и восстановление произвольного контекста. Наличие exportContext не означает возможность самостоятельного восстановления произвольного контекста. Для сохранения результатов используйте фактически открытые в экземпляре исходные возможности ресурсов; не придумывайте action.
Соглашения по языку и регионам
Сохраняйте границы между UI locale, словарём запросов, языком ответа и именами исходных полей.
Приоритет: явно запрошенный язык, язык прикладной системы, locale фактического исполняющего узла. Отсутствующее значение, null, пустая строка и строка из пробелов не приводят к безусловному откату на китайский. Значения регионов в languageRegistry должны оставаться точными; en-GB, fr-CA, pt-BR, es-US или ar-AE нельзя произвольно сворачивать в другой регион.
| Язык или регион | Locale запросов | Описание |
|---|---|---|
| Упрощённый китайский, традиционный китайский | zh-CN zh-Hant | Исходные китайские правила и традиционный каталог различаются |
| Английский (США, Великобритания, Австралия, Канада) | en-US en-GB en-AU en-CA | UI/пакеты ключевых слов могут использоваться совместно, региональные метаданные сохраняются |
| Немецкий, итальянский, русский | de-DE it-IT ru-RU | Используется согласно текущим предложениям сеанса |
| Испанский (Испания и Латинская Америка) | es-ES es-US | ID региона в продукте — es-US |
| Французский (Франция и Канада) | fr-FR fr-CA | Региональные ID не объединяются |
| Португальский (Португалия и Бразилия) | pt-PT pt-BR | Каталог и региональные соглашения сохраняются отдельно |
| Нидерландский, датский, норвежский, финский, шведский | nl-NL da-DK nb-NO fi-FI sv-SE | Норвежский — Bokmål |
| Японский, корейский | ja-JP ko-KR | Не разбивать на слова по пробелам, как в английском |
| Арабский (Саудовская Аравия и ОАЭ) | ar-SA ar-AE | Пояснения интерфейса поддерживают RTL; идентификаторы протокола не инвертируются |
Использование каталога ключевых слов
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}Статический каталог ключевых слов dfc_manual содержит только явно перечисленные locale; если locale не указан, используется английская справочная версия — это справочное значение по умолчанию, а не правило разбора языка запросов. Если для регионального варианта статический каталог не предоставлен, получайте фактические предложения через assist текущего сеанса; не придумывайте псевдонимы и резервные результаты. За один вызов в names — не более 32 элементов.
Что не переводится
- Таблицы, столбцы, значения перечислений, имена клиентов, имена формул и прочие фактические строки модели.
- Имена инструментов, action, scope, поля Schema, коды ошибок и значения состояний.
- ID ресурсов, хеши, opaque locator и ссылки, выданные сервером.
Например, вопрос на немецком языке может обращаться к столбцу с китайским отображаемым именем «销售金额». Замена его на немецкое имя столбца создала бы другой идентификатор, а не перевод интерфейса. После смены языка заново инициализируйте или обновите сеанс по исходному протоколу и заново получите предложения и кандидатов для устранения неоднозначности.
Объединённый анализ и интерактивные результаты
В условно открытых аналитических инструментах сохраняйте авторизацию, версии, ветви и состояние доказательств.
dfc_analysis_* управляется через datafocus.mcp.analysis.tools.enabled. Структурированная часть по-прежнему использует авторитетный запрос Search и текущую политику уровня строк; документная часть заново получает полный исходный текст в рамках текущего ACL. Эти инструменты не являются точкой входа для открытого SQL, произвольных инструкций или внедрения произвольных фильтров.
| Инструмент | Назначение | Необходимые координаты |
|---|---|---|
| dfc_analysis_ask | Задать аналитический вопрос на естественном языке | ontologyId question, необязательный language sessionId |
| dfc_analysis_result_get | Чтение ранее возвращённого результата | ontologyId sessionId resultId |
| dfc_analysis_refine | Уточняющий вопрос или изменение на основе последнего полного результата | Исходный результат expectedRevision и стабильный ключ идемпотентности |
| dfc_analysis_page | Получение одной страницы серверной ветви | Исходная ветвь и версия результата pageNo pageSize |
| dfc_analysis_cancel | Отмена результата, который ещё формируется | Исходный сеанс и результат |
| dfc_analysis_close | Освобождение сеанса, в котором не выполняется работа | Исходный сеанс |
Запуск анализа
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Прочитайте возвращённые sessionId, resultId, статус и revision; при необходимости продолжайте чтение исходного результата.
- Проверяйте статус, полноту, политику уровня строк и источник каждой структурированной ветви по отдельности; завершение одной ветви не означает полноту всего анализа.
- Проверьте документальные доказательства, реестр фактов, пригодность для цитирования и ограничения. Сгенерированный моделью текст не может самостоятельно повысить пригодность доказательств.
- Для уточняющего вопроса опирайтесь на последний полный результат и передавайте expectedRevision; при повторной попытке того же изменения используйте тот же ключ идемпотентности.
- Перед закрытием убедитесь, что в сеансе больше не выполняется работа; отмена и закрытие — разные действия.
Управляемая фильтрация и разбиение на страницы
filter_patch использует предоставленные сервером branchId, fieldRef, valueRef и допустимые операторы; текущий типизированный фильтр объявляет только EQ. Запрещается заменять непрозрачные ссылки сырым SQL, tableId, columnId или самодельным деревом фильтров на стороне клиента. Постраничный параметр pageNo начинается с 1, максимум 10000; pageSize — максимум 100.
Подсказки о возможностях и поведение
Аннотации инструментов (annotations) являются подсказками для клиента, а не механизмом авторизации. Некоторые универсальные шаблоны используют readOnlyHint, что не заменяет оценку фактического действия; отмена, закрытие и создание отчётов изменяют соответствующее рабочее состояние. Всегда выполняйте действия в соответствии с семантикой инструмента, целями пользователя и правами доступа на стороне сервера.
Постоянные визуальные отчёты и MCP Apps
Создавайте восстанавливаемые отчёты и читайте их результаты и интерактивный интерфейс согласно текущим правам доступа.
dfc_report_* управляется через datafocus.mcp.analysis.report-tools.enabled и требует scope metadata и table query. В отличие от сеансов Search, существующих внутри процесса, отчёты используют постоянный reportId; постоянство не означает, что проверка прав больше не выполняется.
{"name":"dfc_report_create","arguments":{
"ontologyId":"<ONTOLOGY_ID>","goal":"比较区域与类别销售表现并核对口径",
"title":"零售经营分析","language":"zh-CN",
"idempotencyKey":"retail-report-20261019-01"
}}
{"name":"dfc_report_status","arguments":{
"ontologyId":"<ONTOLOGY_ID>","reportId":"<REPORT_ID>"
}}Рабочий процесс
- При создании используйте стабильный idempotencyKey длиной от 8 до 128 поддерживаемых символов.
- Сохраните reportId, опрашивайте status и проверяйте фактические состояния: завершено, сбой, частично завершено или отменено.
- При чтении результатов проверяйте структурированные ветви, визуализации, источники фактов, ссылки на документы и полноту.
- Для отмены незавершённого отчёта используйте исходный reportId; не создавайте вместо отмены другой отчёт.
- После сетевого тайм-аута сначала прочитайте состояние исходного отчёта; повторная отправка с исходным ключом идемпотентности должна сохранять то же бизнес-намерение.
MCP Apps
Клиенты с поддержкой UI-расширений считывают страницы отчётов через _meta инструмента и фактическое обнаружение ресурсов. Страница постоянного отчёта для r56 — ui://datafocus/analysis-report/v16/index.html, интерактивный анализ использует соответствующие ссылки на серверные ресурсы; клиент не должен жёстко прописывать эти значения вместо возвращаемых инструментом. Без UI-расширения структурированные результаты по-прежнему доступны для чтения.
Привязка к источнику (Origin)
При чтении отчёта повторно проверяются Grant, онтология, привязка Origin запроса и текущие права доступа к таблице. Кросс-доменная (cross-origin) интеграция в браузере должна использовать одобренные фактические источники; клиент не должен обходить привязку, подделывая Origin. Старый reportId не является долгосрочной публичной ссылкой и не является учётными данными для доступа других пользователей.
Черновики артефактов, предпросмотр, планы и применение
Передавайте сгенерированное содержимое исходному серверу для нормализации, валидации и утверждения; не позволяйте модели напрямую изменять ресурсы рабочей среды.
Инструменты артефактов требуют включённой функции authoring, фактического artifact type, соответствующих scope и исходных прав администратора на запись. По умолчанию настроены типы CONTROL_PANEL_SPEC и VIEW_SPEC; прочие типы (формы, источники HTTP или скрипты) дополнительно управляются отдельными настройками. У Flash нет AutoML, поэтому связанные типы не перечисляются как доступные артефакты в этом выпуске.
- dfc_authoring_capabilities считывает контракты и действия, доступные текущему Grant.
- dfc_artifact_context получает ограниченный контекст, contractVersion, contextHash, baseArtifactHash и baseArtifactVersion.
- На стороне клиента генерируйте кандидатов на основе реальных контрактов, не выполняя содержащийся в них код.
- dfc_artifact_submit отправляет исходный контекст и кандидата, сохраняя instruction неизменным, и использует стабильный clientRequestId.
- Читайте proposalId, candidateHash, результаты проверки и предпросмотр; при фактических ошибках исправляйте кандидата и не подделывайте статус успешной проверки на сервере.
- Когда требуется повторный предпросмотр, используйте dfc_artifact_preview и тот же хеш кандидата.
- dfc_artifact_plan создаёт неизменяемый план, используя реального кандидата, целевую версию и ключ идемпотентности.
- Обрабатывайте утверждение в соответствии с исходным интерактивным процессом или уже авторизованной политикой, затем dfc_artifact_apply; только квитанция APPLIED подтверждает фактическое применение.
Запрос минимального контекста
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC использует текущий авторизованный projectId; при редактировании существующего артефакта используйте фактический artifactId. Поля variables, previewInput, viewport и другие предоставляйте в соответствии с возвращённым контрактом; не придумывайте внутреннюю структуру кандидата.
Параллелизм и повторные попытки
План привязан к целевой версии, хешу кандидата и ключу идемпотентности. После изменения цели старый план не может быть применён; перечитайте контекст и обработайте фактический конфликт. Тайм-аут транспорта не доказывает сбой: сначала с помощью dfc_artifact_status запросите исходный proposalId или planId. READY — это не APPLIED.
Утверждение и автоматическая политика
Для универсальных планов артефактов требуется исходное ручное утверждение. Планы, соответствующие политике автоматической публикации онтологии, обрабатываются согласно approvalMode; от пользователя не требуется дополнительно подписывать придуманное агентом утверждение. approvalToken — это материал, выпущенный сервером, и его нельзя заменить строкой, написанной Agent; фактический inputSchema и квитанция плана определяют обязательные поля.
Контракты создания кандидатов онтологии и публикации
Используйте декларации онтологии и конфигурацию публикации с собственным версионированием; не применяйте к публикации моделей контракты обычных артефактов отображения.
Создание кандидата
Контейнер онтологии должен уже существовать и входить в Grant. Используйте dfc_ontology_table_schema для проверки текущих полей структурированного источника и отпечатка v4 Binding; для поля можно указать только sourceField — тип будет определён автоматически. При явной декларации DECIMAL нужны текущие точность и число знаков после запятой; для других типов эти два поля не передаются.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Кандидат и конфигурация публикации
| Контракт | Назначение | Ключевые границы |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Создание кандидата из локальной декларации | Реальный авторизованный источник, компиляция на сервере; доказательства завершения не принимаются |
| ontology-workspace-create-mcp-submit-v2 | Сочетание локальных деклараций и точных ссылок на опубликованные версии | Требуются точные releaseSelections и зависимости замыкания |
| ontology-publication-mcp-submit-v1 до v3 | Привязка существующего кандидата к запросу плана публикации | Явные координаты; цель, источник, утверждение и валидация восстанавливаются сервером |
| ontology-publication-mcp-submit-v4 до v6 | Отдельно включаемая конфигурация, связанная с автоматической публикацией | Используется, только если это объявлено в capabilities и фактической schema |
| ontology-initial-activation-retirement-submit-v1 | Контролируемые начальные операции активации и вывода из эксплуатации | Отдельный план, новое ручное утверждение и точная область действия |
Порядок публикации
- Получите для текущего кандидата workspaceId, workspaceRevision, candidateHash и фактический источник.
- Выберите версию контракта согласно возможностям сервера; отправьте координаты, такие как releases и selection, без полей, заявляющих «утверждено» или «прошло проверку».
- Сохраните proposalId, возвращённый submit, и исходный idempotencyKey. submit и MODEL_PLAN — разные этапы одного запроса.
- Вызовите dfc_artifact_plan, используя исходного кандидата, целевую версию и тот же ключ идемпотентности.
- PLANNING_INCOMPLETE означает лишь, что действующий план ещё не сформирован; VALIDATION_UNSATISFIED означает, что текущая проверка всё ещё выявляет пробелы; действуйте согласно nextAction.
- После успешного создания плана продолжайте согласно HUMAN_REQUIRED или POLICY_AUTO, используя исходные механизмы утверждения и публикации.
- Подтвердите результат с помощью квитанции APPLIED и последующего фактического чтения опубликованной модели и авторизованных запросов.
Тайм-ауты и восстановление
После тайм-аута PLAN прочитайте исходный proposalId. MODEL_PLAN_SUBMITTED — это незавершённый запрос; MODEL_PLAN_COMPLETED означает, что следует восстановить исходную квитанцию по исходным координатам и исходному ключу, а не создавать новый запрос со стороны клиента. Пробелы, выявленные итоговой проверкой, нельзя превратить в успешную публикацию сменой ключа или повторной отправкой.
Бизнес-полномочия человека
instruction и декларации, предоставленные Agent, являются входными данными Agent, а не утверждением политики человеком. MODEL_AUTHOR, MODEL_PUBLISH, делегирование автоматической публикации, бизнес-подтверждение, доверие к открытым ключам, бюджеты и ACL источников по-прежнему определяются исходными механизмами. Недопустимо заменять эти факты полями клиента.
Опубликованные модели: запрос кандидатов и замыкание ссылок
Используйте опубликованные бизнес-знания по точным версиям и сохраняйте временный характер неопубликованных кандидатов.
published_model, published_query и candidate_query в dfc_ontology_graph — это условно открытые структурированные конфигурации, а не синонимы обычных search/neighbors. Они авторизуются по table query и необходимым правам на чтение моделей; видимость в графе не заменяет прав доступа к таблицам.
Чтение опубликованных моделей
- Когда перечисление action инструмента фактически содержит published_model, отправляйте реальный зафиксированный (committed) releaseId.
- v1 возвращает шаблоны авторизованных запросов; v2 добавляет точные ссылки PERSISTED и releaseSelections; v3 добавляет ссылки на зависимости, точные domainRef и компактные шаблоны привязки.
- Выбирайте объекты, атрибуты, Binding, scope и версии из фактических возвращаемых значений; не генерируйте RID самостоятельно и не используйте latest.
- Отправляйте фиксированные типизированные запросы published_query; результаты всё равно проходят проверку текущих прав на источник и поля.
Запрос кандидатов
candidate_query использует фактический workspaceId, revision, candidateHash и декларации кандидата. Если наряду с ними используются опубликованные ссылки, применяйте соответствующие типизированные координаты v2 LOCAL/PERSISTED и точный выбор. Результаты по кандидату всегда остаются неопубликованными и временными; не считайте их подтверждёнными знаниями организации.
Локальное сопровождение и замыкание
Выбирайте только транзитивные зависимости, необходимые корню кандидата, и обеспечьте точные releaseSelections для каждой опубликованной ссылки. Копирование содержимого публикации, отправка только набора идентификаторов или расширение на все исторические ресурсы не заменяют проверку текущих зависимостей и источников.
Параметр query этих action — версионированный типизированный объект; он не принимает SQL, физические идентификаторы таблиц или имена исходных таблиц вместо бизнес-ссылок. Шаблоны метаданных и результаты графа сами по себе непригодны для цитирования как факты.
Делегирование задач агенту онтологии
Возобновляйте работу через постоянные задачи и исходный Grant; не считайте инструкции Agent утверждением человека.
dfc_ontology_agent отображается только при фактической доступности Pi Runtime и соответствующих прав. QUERY использует возможности чтения; AUTHORING дополнительно требует роль моделирования и соответствующий scope authoring. Инструмент не открывает доступ к какому-либо другому движку выполнения без ограничений.
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"start",
"ontologyId":"<ONTOLOGY_ID>","mode":"QUERY",
"instruction":"列出当前可查询的表,并说明各表用途",
"idempotencyKey":"retail-discovery-01"
}}
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"status",
"ontologyId":"<ONTOLOGY_ID>","runId":"<RUN_ID>"
}}Строгий набор параметров
start использует contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel использует contractVersion, action, ontologyId, runId. Сервер проверяет точный набор полей по action. instruction — максимум 16000 символов; ключ — от 1 до 128 поддерживаемых символов, первый символ — буква или цифра.
Возобновление и отмена
- Сохраняйте исходные runId, Grant, mode и ключ идемпотентности.
- Тот же ключ и та же instruction возобновляют тот же run, новая задача не создаётся; тот же ключ с другой instruction отклоняется.
- status запрашивает состояние исходной задачи. После завершения всё равно проверяйте её запросы к таблицам, доказательства или квитанции публикации.
- Для отмены используйте исходный runId; результат подтверждайте фактическим состоянием задачи.
Завершение run не является квитанцией публикации модели. Задача публикации по-прежнему подтверждается через состояние исходного артефакта и проверки источников; QUERY не даёт подразумеваемых прав на запись или публикацию.
Business Workspace MCP
Запрашивайте записи на основе опубликованных бизнес-контрактов и выполняйте команды через исходный ActionPlan.
/mcp/business использует отдельный protected resource и выбор бизнес-системы; нельзя повторно использовать Grant онтологии вместо бизнес-авторизации. Бизнес-система должна быть опубликована, доступна для вызова из Agent, соответствовать исходной политике безопасности, а у текущего пользователя должны быть фактические роли и возможности среды выполнения.
| Scope | Инструмент | Границы |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Обнаружение только авторизованных и в данный момент вызываемых систем |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Записи, доступные текущему пользователю для чтения, и его собственные планы |
| business-system:plan | dfb_action_plan | Только создание неизменяемого плана, без выполнения |
| business-system:execute | dfb_action_execute | Отдельная явная авторизация, выполнение с учётом риска и утверждений |
- dfb_systems обнаруживает авторизованные системы.
- dfb_system_describe считывает текущие опубликованные контракты, releaseId и все хеши, запросы и команды.
- dfb_query использует опубликованный queryKey, при необходимости указывая objectKey, state, page и pageSize. Это не произвольный SQL.
- dfb_record и dfb_work_items считывают текущие разрешённые записи и задачи.
- Перед выполнением передайте в dfb_action_plan фактические releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey и payload контракта.
- Проверяйте riskClass, requiresApproval и status; если затрагиваются целевые записи, сохраняйте expectedRecordVersion.
- dfb_action_execute выполняет только планы, принадлежащие текущему подключению и находящиеся в состоянии готовности; токены утверждения для обязательного ручного утверждения выдаёт DataFocus.
- После сбоя или тайм-аута dfb_action_status восстанавливает исходный план; повторные попытки сохраняют исходную идемпотентную семантику.
Привязка подключений и версий
План привязан к стабильному изолированному идентификатору текущего Grant. После обновления Access Token планы того же подключения по-прежнему можно обрабатывать, а другое подключение OAuth не может их перехватить. При выполнении повторно проверяются опубликованная версия, хеши IR/manifest, версия целевой записи, срок действия плана, идемпотентность и утверждение. Allowlist OAuth не позволяет обойти бизнес-управление.
Ввод бизнес-знаний и вопросы на подтверждение
Регистрируйте бизнес-ввод, когда открыты соответствующие рабочие обработчики, и сохраняйте границу подтверждения человеком.
Следующие четыре инструмента добавляются публичным контроллером MCP в зависимости от установленных обработчиков и текущих scope. Они не всегда присутствуют в базовом каталоге. Наличие объявленной Schema не означает, что для экземпляра настроены обработчики, бюджеты или права; сначала проверьте tools/list.
| Инструмент | Назначение | Какие права или эффекты не возникают |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Регистрация исходного бизнес-ввода для существующего рабочего пространства | Не генерирует вопросы для подтверждения, не утверждает, не публикует |
| dfc_ontology_knowledge_input_preview | Временный предпросмотр черновиков вопросов из исходного ввода | Не сохраняет, не подтверждает, не формирует квитанцию рабочей среды |
| dfc_ontology_knowledge_question_submit | Сохранение составленных (authored) и неподтверждённых вопросов | Не объединяет ответы автоматически, не даёт прав ответственного лица или прав публикации |
| dfc_ontology_business_scope_initialize | Явная инициализация области потребителя бизнес-системы | Не публикует, не активирует, не предоставляет доступ к источнику |
Ввод и предпросмотр
- Получите workspaceId, workspaceRevision, localRef и preparationDigest из фактической подготовительной работы.
- propose регистрирует бизнес-ввод с исходным контрактом input и стабильным idempotencyKey; один и тот же ключ может соответствовать только одному и тому же вводу.
- preview использует ключ идемпотентности исходного ввода и ontologyId; при каждом вызове он возвращает серверную revision и 60-секундное окно; это не квитанция идемпотентного завершения в рабочей среде.
- Когда требуется сохранить вопрос, question_submit использует новый командный ключ, исходный originalInputKey, явные questionRevision, validFrom, validUntil и expectedRevision; при создании expectedRevision равен null.
Точка подтверждения человеком
knowledgeConfirmationPage, возвращаемый question_submit, — это лишь относительная ссылка на исходную страницу входа с предзаполненным вопросом. Он не содержит Bearer, не открывает страницу автоматически и не подтверждает знание. QUESTION_STORED_UNCONFIRMED явно указывает, что подтверждение ещё не выполнено; в ответе нельзя писать, что «знание опубликовано».
Инициализация области потребителей
business scope initialize требует одновременно права публикации онтологии и прав создателя либо прав управления SourceManager для конкретной бизнес-системы. Он использует реальные координаты domainRid, domainRevisionId и businessSystemId; клиент не может подставить произвольные consumerScope или доказательство завершения. Возвращаемые INITIALIZED и COMPLETED по-прежнему явно содержат published=false и activationAuthorized=false.
Эти запросы также проходят строгую проверку JSON, набора полей, байтов и глубины. Лимит входного запроса — 1 MiB; у отдельных конкретных операций лимиты меньше. Полные схемы ввода и вывода поставляются вместе со справочником инструментов; к этим строгим контрактам нельзя применять нестрогую логику параметров обычной обёртки MCP.
Ответы, ошибки и безопасные повторные попытки
Поясняйте ошибки послойно, сохраняя координаты задач и идемпотентную семантику.
| Уровень | Что проверяется | Принцип обработки |
|---|---|---|
| Сеть и HTTP | Соединение, TLS, 401, 403, 400, 404, 405 и т. д. | Не воспринимайте неудачный ответ как обычный результат запроса |
| JSON-RPC | error.code message data | Различайте проблемы протокола, метода, параметров и авторизации |
| Инструмент MCP | result.isError и structuredContent | Даже при HTTP 200 операция может завершиться неудачей |
| Бизнес-результат | Реальный статус, полнота, причина сбоя, nextAction | Получение или готовность не равны завершению |
| Пригодность в качестве факта | executionReceipt citationEligible contentComplete | Непригодное содержимое используется только для позиционирования или объяснения пробелов |
Типичные ситуации HTTP
- 401: отсутствует или недействителен Bearer — обновите Token или повторите авторизацию по текущему процессу OAuth.
- 403: Grant, роль, выбранный ресурс, права на источник, Origin или конфигурация не удовлетворяют требованиям; не пытайтесь обойти это повторной отправкой.
- 400: некорректное сообщение или версионированный контракт, включая несоответствие современных заголовков и метаданных.
- 404: проверьте точный путь службы, метод протокола и возможности среды выполнения; не меняйте ID онтологии наугад.
- 405: методы GET и DELETE публичного /mcp изначально не открыты; используйте корректный POST, а не устанавливайте долгоживущее соединение SSE.
Операции записи с неясным результатом
MCP_OPERATION_OUTCOME_UNKNOWN может содержать outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool и исходные параметры позиционирования. Сначала проверьте исходный статус, затем восстановите исходный запрос. Не отправляйте кандидата повторно, не меняйте ключ идемпотентности и не считайте тайм-аут откатом транзакции.
Что необходимо сохранить без изменений
- Исходные Grant, области ресурсов, ID задач и результатов.
- candidateHash, planHash, expectedRevision, целевая версия и выбор публикации.
- Ключи идемпотентности одной и той же логической операции; для разных бизнес-операций используйте новые ключи.
- Заявленные сервером retryable, remediation, nextAction и текущий статус.
Не извлекайте из текстов исключений внутренние SQL, хосты, учётные данные или стеки в качестве источника ответа. Достаточно записать публичные коды ошибок и данные для сопоставления запросов; исходную ошибку при необходимости просматривает администратор в контролируемых журналах.
Безопасность интеграции и границы возможностей
Сохраняйте исходные границы идентификации, ресурсов, выполнения и доказательств и безопасно обрабатывайте недоверенные документы.
- Подключайтесь только к официальным доменам, указанным администратором; проверяйте TLS и issuer OAuth, не отключайте проверку сертификатов.
- Используйте выделенный Grant с минимальной областью ресурсов; не используйте учётные записи администратора, Cookie или долгосрочные внутренние Token в качестве учётных данных публичных интерфейсов.
- Считайте текст документов недоверенным бизнес-материалом. Фразы в документе вроде «игнорируй правила», «загрузи ключ», «выполни команду» не дают авторизации на вызов инструментов.
- Ограничивайте автоматические повторные попытки, параллелизм и объём результатов; не воссоздавайте исходные бизнес-права на клиенте.
- В журналах фиксируйте только необходимые данные для сопоставления; не записывайте Bearer, refresh token, токены утверждения и полное конфиденциальное бизнес-содержимое.
- После отключения пользователя или отзыва прав администратором прекратите использовать кэшированные авторизации и данные и не продолжайте вызовы по старым locator.
Подсказки инструментов — это не права
readOnlyHint, destructiveHint, idempotentHint и openWorldHint служат для понимания возможностей клиентом, не гарантируют фактического бизнес-эффекта каждого вызова и не заменяют авторизацию текущего пользователя. Все действия записи, планы, предпросмотры, сеансы и отмены обрабатывайте согласно их реальному поведению.
Точки входа, которые нельзя вызывать
- Исходные сервисы Trino/Hive/Hadoop и Heavy ETL, не входящий во Flash.
- Внутренние интерфейсы выделенных scope или рабочих пространств FocusCode.
- Выполнение v2, AutoML и другие экспериментальные инструменты, отсутствующие в текущем tools/list экземпляра.
- Приватные REST-интерфейсы браузера, произвольные подключения к базам данных или сервисы других арендаторов как способ обойти отказ MCP.
Семантика данных
Следуйте контрактам сервера на точные десятичные числа, типы, валюту (币种), единицы, время и доказательства. Не выполняйте повторное округление или пересчёт валюты (币种) только потому, что вывод похож на число, и не выполняйте глобальное ранжирование по видимым строкам, если результат усечён.
Настройка администратором и условные переключатели
Перед включением расширенных возможностей проверьте фактические компоненты, публичные адреса и исходную конфигурацию прав.
| Конфигурация | Назначение | Требования к выпуску |
|---|---|---|
| datafocus.mcp.public-base-url | Официальный внешний корневой адрес | Согласованность обнаружения OAuth, issuer, обратных вызовов и обратного прокси |
| datafocus.mcp.allowed-origins | Дополнительные одобренные источники (Origin) браузера | Точная конфигурация без расширения до произвольных источников |
| datafocus.mcp.oauth.route-proof-secret | Выделенный секрет сервера для подтверждения маршрутизации графа | Хранится отдельно; Bearer не используется в качестве ключа |
| datafocus.mcp.analysis.tools.enabled | Инструменты интерактивного анализа | Реальная доступность сопутствующих служб данных, знаний и прав |
| datafocus.mcp.analysis.report-tools.enabled | Инструменты постоянных отчётов | Доступность сопутствующего хранилища, worker и цепочки восстановления |
| datafocus.mcp.analysis.apps.enabled | Отображение MCP Apps | Заявленная поддержка клиентом и проверка возвращаемого _meta |
| datafocus.mcp.authoring.enabled | Контракты черновиков и моделирования | Сохранение исходных прав администратора и ресурсов |
| datafocus.mcp.authoring.apply-enabled | Возможность применения артефактов | Неизменяемый план, исходные утверждения и повторная проверка текущего статуса |
| datafocus.mcp.ontology-published-query-enabled | Опубликованные модели и запросы | Реально зафиксированная (committed) версия и авторизация источника |
| datafocus.mcp.ontology-candidate-query-enabled | Структурированные запросы к кандидатам | Владение кандидатом, точная версия и право чтения |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Авторизация, связанная с делегированием автоматической публикации | Действующая исходная политика, доверие к открытому ключу, бюджет и право публикации |
Эти названия происходят из конфигурации и реализации r56; возможность включения зависит от сопутствующих служб и исходных контрольных этапов ввода в эксплуатацию. Одно лишь изменение логического значения не добавит отсутствующие обработчики, базы данных, бюджет проверки или политики. Видимость расширения ввода знаний и задач Pi определяется фактически установленными компонентами.
Пограничный прокси
Сохраняйте Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name и одобренный Origin. Настраивайте тело запроса, тайм-ауты и TLS согласно требованиям фактических служб; не перенаправляйте публичный /mcp на административный порт или другой продукт.
Чек-лист запуска
- Статусы анонимного обнаружения и защищённых вызовов соответствуют ожиданиям.
- Обычные пользователи обнаруживают только свою область авторизации; после отзыва прав последующие запросы отклоняются.
- Нативные сеансы Search, SQL, исходные тексты и необязательные отчёты дают реальные результаты.
- Утверждения для записи и публикации, а также идемпотентное восстановление сохраняют исходное поведение.
- Журналы и публичная документация не содержат приватных ключей, Token, Cookie, паролей и внутренних данных клиентов.
Готовый к запуску клиент и примеры вызовов
Проверяйте сообщения с помощью прилагаемого минимального клиента, не обходя OAuth или текущую авторизацию.
examples/flash_mcp.py — это минимальный протокольный клиент, использующий только стандартную библиотеку Python. Он не выполняет вход, не выполняет утверждение от имени пользователя, не вызывает автоматически невидимые инструменты, поддерживает современные и старые протоколы и при завершении раздельно обрабатывает ошибки уровней HTTP, JSON-RPC и инструментов. Token передаётся через переменные окружения процесса и не записывается в скрипты или файлы документации.
export FLASH_BASE_URL='https://flash.example.com'
read -r -s -p 'Access token: ' FLASH_ACCESS_TOKEN
export FLASH_ACCESS_TOKEN
python3 examples/flash_mcp.py discover
python3 examples/flash_mcp.py tools
python3 examples/flash_mcp.py call dfc_ontologies --arguments '{"page":1,"pageSize":20}'
unset FLASH_ACCESS_TOKENЧтение и запросы
python3 examples/flash_mcp.py call dfc_ontology_resources \
--arguments-file examples/requests/ontology-resources.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/table-detail.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/top3-query.jsonСначала замените заполнители ONTOLOGY_ID, TABLE_RESOURCE_ID и т. д. в файле запроса на реальные значения, возвращённые текущей авторизацией. Обнаружив заполнитель, клиент откажется выполнять запрос. Пример SQL требует, чтобы прилагаемый CSV был импортирован с исходными именами столбцов; без соответствующей схемы отправлять его как есть нельзя.
Другие сценарии
- Бизнес-точка входа: используйте --endpoint business, чтобы заново получить Grant для /mcp/business.
- Старые клиенты: выберите --protocol 2025-11-25, сначала выполните initialize, затем вызывайте по тому же протоколу.
- Встроенные описания: используйте resources или read-resource для чтения фактического URI.
- Автономная самопроверка: --self-test проверяет построение современных заголовков и метаданных; Token не нужен, сервер продукта не запрашивается.
Границы примеров
Клиент — это отправная точка протокольного подключения, он не генерирует кандидатов моделирования, не сохраняет ответы и не выполняет публикацию автоматически. Он выводит исходный JSON, чтобы вышестоящий Agent мог сверить бизнес-статус; не обещайте пользователю завершение запроса, отчёта или публикации только по коду выхода процесса.
Встраивание интерфейса диалога онтологии
Встройте страницу диалога для пользователей в бизнес-фронтенд, сохраняя границы безопасности входа и браузера.
<iframe
title="OT Flash ontology agent"
src="https://flash.example.com/10001/#/embed/ontology-agent/1001"
style="width:100%;height:760px;border:0"
referrerpolicy="strict-origin-when-cross-origin">
</iframe>10001 — ID арендатора из примера, 1001 — ID онтологии из примера; замените их реальными координатами, на которые у вас есть права. Одна онтология может быть указана через path или поддерживаемый query; режим all предоставляет @ для выбора онтологий, доступных текущему пользователю. skillId передаётся без обработки; на этом основании нельзя утверждать, что оркестрация навыков уже доступна для выполнения.
Аутентификация и домены
Текущая страница встраивания требует реального сеанса входа DataFocus и проверяет /uc/status. Кросс-сайтовые Cookie, SSO, CSP frame-ancestors и конфигурация шлюза влияют на встраивание. Передача MCP Bearer в URL как способ обойти вход не поддерживается; нереализованные внешние ссылки outside нельзя собирать самостоятельно по проектным предложениям.
Различие между MCP и iframe
| Способ | Пользователь | Идентификация и результат |
|---|---|---|
| Remote MCP | Внешние Agent или интеграции сервисов | OAuth Grant и структурированные квитанции инструментов |
| iframe-диалог онтологии | Конечный пользователь (человек) | Исходное состояние входа и интерфейс диалога |
| MCP Apps | Клиент MCP с поддержкой расширений | Управляемые ресурсы и текущие результаты инструментов, а не публичная замена входа через iframe |
Чек-лист приёмочной проверки интеграции
Подтвердите полную бизнес-цепочку на реальном экземпляре, а не только то, что интерфейсы возвращают 200.
- Обнаружение: получите фактически поддерживаемые версии, текущий каталог инструментов и встроенные ресурсы.
- Авторизация: обычные пользователи видят только разрешённые онтологии и бизнес-системы; операции без scope отклоняются.
- Структура таблиц: реальные отображаемые имена, столбцы, типы и права доступа представлены полностью.
- SQL: проверки одномерных и многомерных запросов, JOIN, дат, TopN и усечения соответствуют фактической бизнес-методике.
- Знания: позиционирование, полный исходный текст и пригодность для цитирования как факта согласованы; смешанные вопросы опираются одновременно на данные и документы.
- Search: модель, init, предложения, результаты, закрытие и проверки целостности буфера пройдены.
- Необязательные анализ и отчёты: реальные состояния нескольких ветвей, переход по страницам, изменение прав и отмена работают как в исходной системе.
- Необязательное моделирование: кандидат, план, исходное утверждение, фактическое применение и запрос версии проверяются поэтапно.
- Бизнес-действия: хеш публикации, целевая версия, утверждение, идемпотентность и изоляция между Grant проверены.
- Восстановление: после сетевого тайм-аута восстанавливается исходное состояние, после обновления источника старое позиционирование перестаёт действовать и используется новый запрос.
Запись результатов
Записывайте версию экземпляра, роль пользователя, область Grant, версию конфигурации, фактические операции и результаты. Отдельно помечайте офлайн-самопроверку клиента протокола, ожидаемые значения для примеров CSV, рассчитанные офлайн, статическую проверку по схеме JSON и реальную функциональную приёмку в рабочей среде. Не экстраполируйте успешное прохождение одного этапа на успешное прохождение всего продукта.
Нормативные ресурсы и сопровождение
Используйте прилагаемые к руководству полные схемы инструментов и сверяйте их с фактическими результатами обнаружения на экземпляре.
| Ресурсы | Содержание |
|---|---|
| reference/mcp-tool-catalog.json | Объявленные входные Schema для 32 инструментов онтологии и 8 бизнес-инструментов; для части инструментов есть и исходные выходные Schema |
| reference/locales.json | 21 доступный для выбора вариант, 24 совместимых locale и термины UI |
| reference/search-keywords.json | Статические каталоги ключевых слов для 17 явно указанных locale |
| reference/analysis-contract-manifest.json | Ограничения версий, связанные с анализом, ветвями, фактами, квитанциями и отчётами |
| examples/ | Синтетические CSV, описание методики расчёта, Top3 SQL, ожидаемые результаты и минимальный клиент протокола |
Встроенные справочные ресурсы
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list и resources/read требуют, чтобы текущий пользователь обладал хотя бы одним из соответствующих прав на чтение: metadata, operate для search или operate для ETL. Документация ETL является статическим межпродуктовым справочником; исполняемые возможности Flash по-прежнему ограничены тем, о чём он явно сообщает.
Внешние справочные материалы по протоколу
По протоколу MCP и вопросам авторизации обращайтесь к официальным спецификациям: https://modelcontextprotocol.io/specification/2026-07-28/basic и https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. Конечные точки, инструменты и условное поведение данного продукта определяются реализацией r56 и фактически обнаруженными на экземпляре результатами; общую поддержку протокола нельзя приравнивать к наличию на сервере всех необязательных возможностей.
Обновление и сопровождение
При обновлении заново выполняйте обнаружение инструментов и версий, сравнивайте входные схемы, выходные контракты и конфигурацию; старые Grant автоматически не получают новых scope. Сохраняйте привязку ссылок, кэша и квитанций к версии источника; после подтверждения несовместимых изменений заново получайте контекст и не применяйте старое позиционирование к новому бизнес-состоянию.
Справочник параметров инструментов: базовые инструменты и нативный Search
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfc_manual
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| names | array | Опционально или условно обязательно | Искомые явные имена, не более 32 за один вызов. maxItems: 32 |
| action | string | Опционально или условно обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: list, read, keywords, functions, etl_requests |
| locale | string | Опционально или условно обязательно | Явно заданный locale статического справочного каталога; это не язык запросов по умолчанию. |
| uri | string | Опционально или условно обязательно | URI встроенных ресурсов, перечисленных текущим инструментом. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| data | object | Опционально или условно обязательно | Полезная нагрузка исходного действия; см. таблицу обнаружения возможностей и полей действий. |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| data | object | Опционально или условно обязательно | Полезная нагрузка исходного действия; см. таблицу обнаружения возможностей и полей действий. |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: capabilities |
dfc_ontologies
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| pageSize | integer | Опционально или условно обязательно | Количество записей на странице; в пределах лимита Schema. minimum: 1; maximum: 100 |
| page | integer | Опционально или условно обязательно | Номер страницы, начиная с 1. minimum: 1 |
dfc_ontology_resources
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| resourceTypes | array | Опционально или условно обязательно | Набор типов возвращаемых ресурсов. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| pageSize | integer | Опционально или условно обязательно | Количество записей на странице; в пределах лимита Schema. minimum: 1; maximum: 100 |
| page | integer | Опционально или условно обязательно | Номер страницы, начиная с 1. minimum: 1 |
Справочник параметров инструментов: таблицы, граф и знания
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfc_ontology_graph
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| relationTypes | array | Опционально или условно обязательно | Фильтр по типу связи. |
| depth | integer | Опционально или условно обязательно | Глубина обхода соседей. minimum: 1; maximum: 3 |
| sourceTypes | array | Опционально или условно обязательно | Фильтр по типу источника. |
| query | object | Опционально или условно обязательно | Текст запроса или точный версионированный объект запроса, соответствующий action. |
| limit | integer | Опционально или условно обязательно | Верхний предел количества возвращаемых результатов. minimum: 1; maximum: 100 |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| nodeKey | string | Опционально или условно обязательно | Ключ узла, скопированный из фактических результатов графа. |
| keyword | string | Опционально или условно обязательно | Ключевые слова для позиционирования в графе, а не синтаксис запросов данных по ключевым словам. |
| nodeTypes | array | Опционально или условно обязательно | Фильтр по типу узла. |
dfc_ontology_query
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| routeLocators | array | Опционально или условно обязательно | Полная копия выданных сервером типизированных локаторов маршрута. maxItems: 20 |
| topK | integer | Опционально или условно обязательно | Верхний предел возвращаемых кандидатов; не гарантирует полноту покрытия. minimum: 1; maximum: 20 |
| queryMode | string | Опционально или условно обязательно | Режим поиска доказательств, выбираемый по перечислению инструмента. enum: vector, hybrid, graph |
| fanoutPlan | object | Опционально или условно обязательно | План ограниченного поиска по ветвям согласно вложенной Schema. |
| structuredPlan | object | Опционально или условно обязательно | План для полной таблицы из документа, привязанный к серверному контракту; не SQL. |
| knowledgeIds | array | Опционально или условно обязательно | ID базы знаний из фактических knowledgeBindings. |
| query | string | Обязательно | Текст запроса или точный версионированный объект запроса, соответствующий action. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
dfc_knowledge_search
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| topK | integer | Опционально или условно обязательно | Верхний предел возвращаемых кандидатов; не гарантирует полноту покрытия. minimum: 1; maximum: 20 |
| minScore | number | Опционально или условно обязательно | Минимальный балл совпадения. minimum: 0; maximum: 1 |
| knowledgeIds | array | Опционально или условно обязательно | ID базы знаний из фактических knowledgeBindings. |
| query | string | Обязательно | Текст запроса или точный версионированный объект запроса, соответствующий action. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| assetIds | array | Опционально или условно обязательно | Разрешённые в данный момент ID активов-документов. |
| retrievalStrategy | string | Опционально или условно обязательно | Фактически поддерживаемая стратегия поиска. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| qdrantId | string / integer | Опционально или условно обязательно | Идентификатор индекса, возвращённый при фактическом позиционировании. |
| pageNo | integer | Опционально или условно обязательно | Фактический номер страницы документа или страницы выдачи. |
| evidenceId | string | Опционально или условно обязательно | ID доказательства из того же результата позиционирования знаний. |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: chunk, document, page_context |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| documentId | string / integer | Опционально или условно обязательно | ID документа из того же результата позиционирования. |
| radius | integer | Опционально или условно обязательно | Диапазон соседних страниц. minimum: 0; maximum: 3 |
| chunkId | string | Опционально или условно обязательно | Фактический ID фрагмента из того же результата позиционирования. |
dfc_table
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| maxRows | integer | Опционально или условно обязательно | Верхний предел числа возвращаемых строк; не диапазон ранжирования на клиенте. minimum: 1; maximum: 200 |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: detail, query |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| id | string | Опционально или условно обязательно | Реальный ID ресурса таблицы, не физическое или отображаемое имя. |
| sql | string | Опционально или условно обязательно | Один SQL-запрос Doris только на чтение в рамках онтологии, с явными выходными столбцами. |
Справочник параметров инструментов: анализ и отчёты
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfc_analysis_ask
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| question | string | Обязательно | Вопрос на естественном языке или совместимый уточняющий вопрос. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| language | string | Опционально или условно обязательно | Явно заданный locale ответа или запроса; если не указан — по правилам соответствующего инструмента. |
| sessionId | string | Опционально или условно обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
dfc_analysis_refine
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| branchId | string | Опционально или условно обязательно | Выданный сервером идентификатор структурированной ветви. |
| resultId | string | Обязательно | Идентификатор результата анализа из исходного ответа. |
| question | string | Опционально или условно обязательно | Вопрос на естественном языке или совместимый уточняющий вопрос. |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| change | object | Опционально или условно обязательно | Изменение на естественном языке или типизированный filter_patch. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| language | string | Опционально или условно обязательно | Явно заданный locale ответа или запроса; если не указан — по правилам соответствующего инструмента. |
| sessionId | string | Обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
| expectedRevision | integer | Обязательно | Ожидаемая версия исходного результата или бизнес-заголовка (предусловие); при создании вопроса может быть null. minimum: 1 |
| visualId | string | Опционально или условно обязательно | Идентификатор визуализации, привязанный к ветви. |
dfc_analysis_page
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| branchId | string | Обязательно | Выданный сервером идентификатор структурированной ветви. |
| resultId | string | Обязательно | Идентификатор результата анализа из исходного ответа. |
| pageNo | integer | Обязательно | Фактический номер страницы документа или страницы выдачи. minimum: 1; maximum: 10000 |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| pageSize | integer | Обязательно | Количество записей на странице; в пределах лимита Schema. minimum: 1; maximum: 100 |
| sessionId | string | Обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
| expectedRevision | integer | Обязательно | Ожидаемая версия исходного результата или бизнес-заголовка (предусловие); при создании вопроса может быть null. minimum: 1 |
dfc_analysis_result_get
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| resultId | string | Обязательно | Идентификатор результата анализа из исходного ответа. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| sessionId | string | Обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
dfc_analysis_cancel
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| resultId | string | Обязательно | Идентификатор результата анализа из исходного ответа. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| sessionId | string | Обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
dfc_analysis_close
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| sessionId | string | Обязательно | Реальный идентификатор сеанса в рамках того же Grant. |
dfc_report_create
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| goal | string | Обязательно | Цель анализа для отчёта. |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| language | string | Опционально или условно обязательно | Явно заданный locale ответа или запроса; если не указан — по правилам соответствующего инструмента. |
| title | string | Опционально или условно обязательно | Необязательный заголовок отчёта. |
dfc_report_status
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| reportId | string | Обязательно | Идентификатор постоянного отчёта текущего Grant. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
dfc_report_cancel
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| reportId | string | Обязательно | Идентификатор постоянного отчёта текущего Grant. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
Справочник параметров инструментов: моделирование и исходные задачи
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfc_ontology_agent
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| mode | string | Опционально или условно обязательно | QUERY или AUTHORING; права на эти возможности предоставляются по отдельности. enum: QUERY, AUTHORING |
| instruction | string | Опционально или условно обязательно | Текст запроса пользователя; в context и submit он должен совпадать. maxLength: 16000 |
| idempotencyKey | string | Опционально или условно обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. maxLength: 128 |
| action | string | Обязательно | Имя операции. Используется в соответствии с текущим перечислением и параметрами соответствующего действия. enum: start, status, cancel |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| runId | string | Опционально или условно обязательно | ID исходной задачи той же онтологии и того же Grant. |
| contractVersion | string | Обязательно | Точная фактически поддерживаемая версия контракта. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
Корневой объект ввода этого инструмента не содержит полей; используйте пустой объект arguments.
dfc_artifact_context
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Опционально или условно обязательно | Тип области ресурсов из фактического контракта артефакта. |
| ontologyId | string | Опционально или условно обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| projectId | string | Опционально или условно обязательно | ID текущего авторизованного проекта. |
| artifactId | string | Опционально или условно обязательно | Реальный ID редактируемого существующего артефакта. |
| instruction | string | Обязательно | Текст запроса пользователя; в context и submit он должен совпадать. |
| variables | object | Опционально или условно обязательно | Объект переменных, предоставляемый согласно возвращённому контракту. |
| previewInput | object | Опционально или условно обязательно | Ограниченный ввод предпросмотра, предоставляемый согласно контракту. |
| viewport | object | Опционально или условно обязательно | Область просмотра (viewport), требуемая исходным контрактом. |
dfc_ontology_table_schema
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| sourceAssetRef | string | Обязательно | Зарегистрированная ссылка на структурированный актив, например table:123. |
| fields | array | Обязательно | Поля текущего источника с необязательными явными объявлениями типов. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| proposalId | string | Обязательно | ID исходного кандидата, созданного в рамках текущего Grant. |
| candidateHash | string | Обязательно | Точный хеш исходного кандидата, выданного сервером. |
| previewInput | object | Обязательно | Ограниченный ввод предпросмотра, предоставляемый согласно контракту. |
dfc_artifact_status
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| proposalId | string | Опционально или условно обязательно | ID исходного кандидата, созданного в рамках текущего Grant. |
| planId | string | Опционально или условно обязательно | ID неизменяемого плана применения. |
dfc_artifact_plan
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| proposalId | string | Обязательно | ID исходного кандидата, созданного в рамках текущего Grant. |
| candidateHash | string | Обязательно | Точный хеш исходного кандидата, выданного сервером. |
| expectedTargetVersion | integer | Обязательно | Текущая реальная целевая версия (предусловие). minimum: 0 |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
dfc_artifact_apply
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| planId | string | Обязательно | ID неизменяемого плана применения. |
| planHash | string | Обязательно | Хеш, возвращённый исходным планом. |
| approvalToken | string | Обязательно | Материалы утверждения, выданные исходным сервером; генерировать их самостоятельно запрещено. |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
dfc_artifact_submit
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| Конфигурация 1 / artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Конфигурация 1 / scopeType | string | Опционально или условно обязательно | Тип области ресурсов из фактического контракта артефакта. |
| Конфигурация 1 / ontologyId | string | Опционально или условно обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| Конфигурация 1 / projectId | string | Опционально или условно обязательно | ID текущего авторизованного проекта. |
| Конфигурация 1 / artifactId | string | Опционально или условно обязательно | Реальный ID редактируемого существующего артефакта. |
| Конфигурация 1 / instruction | string | Обязательно | Текст запроса пользователя; в context и submit он должен совпадать. |
| Конфигурация 1 / variables | object | Опционально или условно обязательно | Объект переменных, предоставляемый согласно возвращённому контракту. |
| Конфигурация 1 / previewInput | object | Опционально или условно обязательно | Ограниченный ввод предпросмотра, предоставляемый согласно контракту. |
| Конфигурация 1 / viewport | object | Опционально или условно обязательно | Область просмотра (viewport), требуемая исходным контрактом. |
| Конфигурация 1 / contractVersion | string | Обязательно | Необходимо использовать точную фактически поддерживаемую версию контракта. |
| Конфигурация 1 / contextHash | string | Обязательно | Полный хеш контекста, возвращённый context. |
| Конфигурация 1 / baseArtifactHash | string | Обязательно | Хеш базового артефакта, возвращённый context. |
| Конфигурация 1 / baseArtifactVersion | integer | Обязательно | Базовая версия, возвращённая context. minimum: 0 |
| Конфигурация 1 / candidate | object | Обязательно | Кандидат, соответствующий текущему возвращённому контракту. |
| Конфигурация 1 / clientRequestId | string | Обязательно | Клиентский ключ идемпотентности, стабильно используемый для текущего запроса кандидата. |
| Конфигурация 2 / artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: ONTOLOGY_RELEASE |
| Конфигурация 2 / contractVersion | string | Обязательно | Необходимо использовать точную фактически поддерживаемую версию контракта. enum: ontology-publication-mcp-submit-v1, ontology-publication-mcp-submit-v2, ontology-publication-mcp-submit-v3, ontology-publication-mcp-submit-v4, ontology-publication-mcp-submit-v5, ontology-publication-mcp-submit-v6 |
| Конфигурация 2 / ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| Конфигурация 2 / candidateHash | string | Обязательно | Точный хеш исходного кандидата, выданного сервером. |
| Конфигурация 2 / workspaceId | string | Обязательно | Фактические координаты рабочего пространства кандидата. |
| Конфигурация 2 / workspaceRevision | string | Обязательно | Точная версия кандидата; latest не используется. |
| Конфигурация 2 / releases | object | Обязательно | Выбор точной версии согласно контракту публикации онтологии. |
| Конфигурация 2 / selection | object | Обязательно | Предоставляются только явные координаты бизнес-выбора; доказательства прав или завершения не передаются. |
| Конфигурация 2 / idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| Конфигурация 3 / Конфигурация 1 / artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: ONTOLOGY_RELEASE |
| Конфигурация 3 / Конфигурация 1 / contractVersion | string | Обязательно | Необходимо использовать точную фактически поддерживаемую версию контракта. enum: ontology-workspace-create-mcp-submit-v1 |
| Конфигурация 3 / Конфигурация 1 / ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| Конфигурация 3 / Конфигурация 1 / workspaceId | string | Обязательно | Фактические координаты рабочего пространства кандидата. |
| Конфигурация 3 / Конфигурация 1 / resources | array | Обязательно | Декларации исходной модели, компилируемые сервером. minItems: 1 |
| Конфигурация 3 / Конфигурация 1 / idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| Конфигурация 3 / Конфигурация 2 / artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: ONTOLOGY_RELEASE |
| Конфигурация 3 / Конфигурация 2 / contractVersion | string | Обязательно | Необходимо использовать точную фактически поддерживаемую версию контракта. enum: ontology-workspace-create-mcp-submit-v2 |
| Конфигурация 3 / Конфигурация 2 / ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| Конфигурация 3 / Конфигурация 2 / workspaceId | string | Обязательно | Фактические координаты рабочего пространства кандидата. |
| Конфигурация 3 / Конфигурация 2 / resources | array | Обязательно | Декларации исходной модели, компилируемые сервером. minItems: 1 |
| Конфигурация 3 / Конфигурация 2 / idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| Конфигурация 3 / Конфигурация 2 / releaseSelections | object | Обязательно | Точная releaseId каждой опубликованной ссылки и замыкание зависимостей. |
| Конфигурация 4 / artifactType | string | Обязательно | Фактически включённый тип артефакта или публикации онтологии. enum: ONTOLOGY_RELEASE |
| Конфигурация 4 / contractVersion | string | Обязательно | Необходимо использовать точную фактически поддерживаемую версию контракта. enum: ontology-initial-activation-retirement-submit-v1 |
| Конфигурация 4 / ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| Конфигурация 4 / domainRid | string | Обязательно | Реальный RID бизнес-домена. |
| Конфигурация 4 / consumerScopes | array | Обязательно | Точные области потребителей, разрешённые сервером. minItems: 1; maxItems: 256 |
| Конфигурация 4 / idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
Справочник параметров инструментов: ввод знаний и бизнес-области
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfc_ontology_knowledge_input_propose
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| request | object | Обязательно | Исходный запрос бизнес-ввода; по полной вложенной Schema. |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый повторно для одной и той же логической операции. minLength: 1; maxLength: 128 |
У этого инструмента есть собственный нативный outputSchema. Проверяйте полноту вывода, статус и поля авторизации, явно равные false; не расширяйте самостоятельно смысл завершения.
dfc_ontology_knowledge_input_preview
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый повторно для одной и той же логической операции. minLength: 1; maxLength: 128 |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
У этого инструмента есть собственный нативный outputSchema. Проверяйте полноту вывода, статус и поля авторизации, явно равные false; не расширяйте самостоятельно смысл завершения.
dfc_ontology_knowledge_question_submit
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| questionRevision | $ref | Обязательно | Точная версия текущего вопроса, ожидающего подтверждения. |
| idempotencyKey | $ref | Обязательно | Ключ идемпотентности, стабильно используемый для одной и той же логической операции. |
| originalInputKey | $ref | Обязательно | Ключ идемпотентности, соответствующий исходному вводу знаний. |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. |
| validUntil | $ref | Обязательно | Конец окна действия вопроса, время UTC. |
| expectedRevision | oneOf | Обязательно | Ожидаемая версия исходного результата или бизнес-заголовка (предусловие); при создании вопроса может быть null. |
| validFrom | $ref | Обязательно | Начало окна действия вопроса, время UTC. |
У этого инструмента есть собственный нативный outputSchema. Проверяйте полноту вывода, статус и поля авторизации, явно равные false; не расширяйте самостоятельно смысл завершения.
dfc_ontology_business_scope_initialize
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| domainRevisionId | string | Обязательно | Точная версия бизнес-домена. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Обязательно | Ключ идемпотентности, стабильно используемый повторно для одной и той же логической операции. minLength: 1; maxLength: 128 |
| businessSystemId | string | Обязательно | Реальный ID бизнес-системы. minLength: 1 |
| ontologyId | string | Обязательно | Реальный ID онтологии в рамках текущей авторизации, сохраняемый как строка. minLength: 1 |
| domainRid | string | Обязательно | Реальный RID бизнес-домена. minLength: 1; maxLength: 128 |
У этого инструмента есть собственный нативный outputSchema. Проверяйте полноту вывода, статус и поля авторизации, явно равные false; не расширяйте самостоятельно смысл завершения.
Справочник параметров инструментов: Business Workspace
Полные имена и поля ввода, сгруппированные по инструментам.
Приведённые ниже таблицы — справочник по полям ввода текущих инструментов r56. Полные вложенные типы, oneOf, условно обязательные поля, ограничения pattern и часть выходных Schema см. в reference/mcp-tool-catalog.json; перед финальной отправкой всё равно считайте tools/list текущего Grant. Пометка «опционально» в таблице не отменяет внутренних требований валидации действия.
dfb_systems
Корневой объект ввода этого инструмента не содержит полей; используйте пустой объект arguments.
dfb_system_describe
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| systemId | string / integer | Обязательно | ID систем, разрешённых текущим бизнес-Grant. |
dfb_query
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| systemId | string / integer | Обязательно | ID систем, разрешённых текущим бизнес-Grant. |
| queryKey | string | Обязательно | Опубликованный ключ запроса, возвращённый describe. |
| objectKey | string | Опционально или условно обязательно | Ключ опубликованного объекта. |
| pageSize | integer | Опционально или условно обязательно | Количество записей на странице; в пределах лимита Schema. minimum: 1; maximum: 100 |
| page | integer | Опционально или условно обязательно | Номер страницы, начиная с 1. minimum: 1 |
| state | string | Опционально или условно обязательно | Фильтр бизнес-статуса или статус на стороне сервера. |
dfb_record
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| recordId | string / integer | Обязательно | ID бизнес-записи, разрешённой к чтению в данный момент. |
| systemId | string / integer | Обязательно | ID систем, разрешённых текущим бизнес-Grant. |
dfb_work_items
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| systemId | string / integer | Обязательно | ID систем, разрешённых текущим бизнес-Grant. |
dfb_action_plan
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| expectedRecordVersion | integer | Опционально или условно обязательно | Текущая версия оптимистичной блокировки целевой записи. minimum: 1 |
| systemId | string / integer | Обязательно | ID систем, разрешённых текущим бизнес-Grant. |
| commandType | string | Обязательно | Тип команды из опубликованного контракта. |
| canonicalIrHash | string | Обязательно | Хеш канонического IR текущей опубликованной версии. |
| releaseId | string / integer | Обязательно | Фактический ID версии опубликованного контракта. |
| payload | object | Обязательно | Полезная нагрузка, соответствующая текущему контракту команды в describe. |
| releaseHash | string | Обязательно | Фактический хеш опубликованного контракта. |
| targetRecordId | string / integer | Опционально или условно обязательно | Реальная целевая запись, над которой требуется выполнить операцию. |
| agentManifestHash | string | Обязательно | Фактический хеш manifest возможностей Agent. |
| planIdempotencyKey | string | Обязательно | Стабильный ключ идемпотентности бизнес-плана. |
dfb_action_status
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| actionPlanId | string / integer | Обязательно | ID плана действий, принадлежащего текущему бизнес-Grant. |
dfb_action_execute
| Параметр | Тип | Требование | Значение и диапазон |
|---|---|---|---|
| approvalToken | string | Опционально или условно обязательно | Материалы утверждения, выданные исходным сервером; генерировать их самостоятельно запрещено. |
| actionPlanId | string / integer | Обязательно | ID плана действий, принадлежащего текущему бизнес-Grant. |