Manual de integração do Agent e do MCP do OT Flash
Protocolo, autorização, contratos de ferramentas e fluxo completo de chamada
Construa aplicações de dados e conhecimento rastreáveis usando o Remote MCP público do OT Flash r56. Este manual apresenta OAuth, mensagens de protocolo, referência de parâmetros de todas as ferramentas declaradas, regras de evidência, capacidades condicionais e fluxos de recuperação, além de exemplos de cliente executável e dados sintéticos.
Desenvolvedores de Agent, engenheiros de integração e administradores
Os exemplos complementares mantêm em chinês os nomes de exibição dos campos. A tradução da interface e do texto explicativo não altera nomes reais de tabelas, colunas, valores de enumeração, nomes de ferramentas ou campos de protocolo.
Sumário
- 1Escopo de integração do Agent e critérios de conclusão
- 2Conexão rápida e descoberta de capacidades
- 3OAuth: descoberta, registro e autorização
- 4Scope, limites de recursos e permissões em tempo real
- 5Mensagens HTTP e do MCP moderno
- 6Compatibilidade com clientes de protocolo legado
- 7Escolher a ferramenta correta e o canal de evidências
- 8Recursos da ontologia e tipos de ID
- 9Consulta de tabelas Doris e contrato de estrutura
- 10Top3 multidimensional e tratamento de truncamento
- 11Recuperação de conhecimento: texto original completo e elegibilidade de evidência
- 12Modelos e sessões nativos de Search
- 13Convenções de idioma e região
- 14Análise integrada e resultados interativos
- 15Relatórios visuais persistentes e MCP Apps
- 16Rascunhos de artefatos, pré-visualização, planos e aplicação
- 17Contratos de criação e publicação de candidatos de ontologia
- 18Modelo publicado, consultas de candidatos e fecho de referências
- 19Delegação de tarefas ao agente de ontologia
- 20MCP do espaço de trabalho de negócio
- 21Entradas de conhecimento de negócio e perguntas pendentes de confirmação
- 22Resposta, erros e nova tentativa segura
- 23Segurança de integração e limites de capacidade
- 24Configuração do administrador e opções condicionais
- 25Cliente executável e exemplos de chamada
- 26Incorporar a interface de conversa da ontologia
- 27Lista de verificação de aceitação de integração
- 28Recursos de especificação e manutenção
- 29Referência de parâmetros de ferramentas: base e Search nativo
- 30Referência de parâmetros de ferramentas: tabela, grafo e conhecimento
- 31Referência de parâmetros de ferramentas: análise e relatórios
- 32Referência de parâmetros de ferramentas: modelagem e tarefa original
- 33Referência de parâmetros de ferramentas: entrada de conhecimento e escopo
- 34Referência de parâmetros de ferramentas: espaço de trabalho de negócio
Escopo de integração do Agent e critérios de conclusão
Selecione o ponto de entrada de autorização e execute consultas, coleta de evidências ou gravações controladas com base nos recibos do servidor.
O OT Flash r56 fornece capacidades de dados e conhecimento no escopo da ontologia a Agents externos por meio do Remote MCP, além de um ponto de entrada independente para o espaço de trabalho de negócio. O Agent deve definir o trabalho executável com base no tools/list real, no inputSchema, no OAuth scope e nas permissões de recursos atuais; não deve inferir, a partir de um manual estático, que uma implantação já habilitou todas as funcionalidades opcionais.
| Entrada | Finalidade | Limites |
|---|---|---|
| /mcp | Ontologia, tabelas de dados, conhecimento documental, Search nativo e análise e modelagem disponibilizadas condicionalmente | Interseção entre as permissões do usuário atual e os recursos concedidos nesta autorização |
| /mcp/business | Descoberta de sistemas de negócio, consultas, planos de ação, status e execução | Autorização independente de sistemas de negócio e contratos publicados |
| Página de incorporação do agente de ontologia | Usar a conversa de ontologia na interface para usuários humanos | Depende de uma sessão de login real; não é um ponto de entrada para trocar Token MCP sem login |
Classificação de capacidades
- Leitura básica: ontologia e recursos, localização no grafo, recuperação de conhecimento e texto original completo, detalhes de tabelas autorizadas e Doris SQL.
- Delegação independente: dfc_search requer search:operate e continua usando as permissões originais do usuário e do modelo.
- Disponibilidade condicional: análises, relatórios persistentes, rascunho e aplicação de artefatos, consultas ao modelo de ontologia e tarefas delegadas ao Agent.
- Capacidades indisponíveis: o dfc_etl do Flash apenas reporta capabilities e não fornece execução de ETL do Heavy. O AutoML e os pontos de entrada internos de workspace do FocusCode não fazem parte da API pública do Flash descrita neste manual.
Critérios de conclusão
A leitura de fatos exige um recibo de consulta efetivamente utilizável ou de texto original completo; a geração de candidatos exige declarar que eles ainda não foram aplicados; a publicação exige um recibo real de APPLIED; o cancelamento exige distinguir entre solicitação e confirmação. O texto da resposta, um HTTP 200, a aceitação pela ferramenta ou uma descrição de "concluído" dada pelo modelo não provam, isoladamente, o sucesso de uma operação de negócio.
O arquivo complementar reference/mcp-tool-catalog.json é a referência offline das declarações do r56; ele inclui definições habilitadas condicionalmente e não é o tools/list em tempo real de nenhum usuário. O catálogo completo inclui 28 ferramentas centrais de ontologia, 4 extensões condicionais de controlador e 8 ferramentas do lado do negócio, o que não significa que todas estejam habilitadas por padrão.
Conexão rápida e descoberta de capacidades
Comece pelo domínio oficial da instância e descubra as ferramentas realmente disponíveis com privilégios mínimos.
- Obtenha com o administrador o endereço raiz HTTPS oficial e a ontologia ou o sistema de negócio que precisam ser acessados. Não use os domínios de exemplo da documentação em chamadas a operações de negócio reais.
- Configure o endereço do servidor MCP como https://flash.example.com/mcp; o espaço de trabalho de negócio usa /mcp/business no mesmo domínio.
- Acione o login e a autorização do OAuth conforme o suporte do cliente e verifique recursos e scope; não envie nome de usuário e senha ao MCP.
- Use a descoberta ou a inicialização da geração de protocolo correspondente e, em seguida, leia o tools/list e as descrições dos recursos.
- Faça primeiro uma pequena solicitação somente leitura, verifique os resultados estruturados e os erros e só então execute o objetivo do usuário.
Trecho de configuração do cliente
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Este trecho ilustra a intenção de configuração do endereço do servidor; a estrutura específica do arquivo de configuração e o suporte a OAuth dependem do cliente. Não insira access_token, refresh_token, Cookie ou senhas de administrador reais em arquivos públicos.
Descoberta de protocolo moderno
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": {}
}
}
}Verificações antes da integração
- O endereço raiz do recurso, o issuer do OAuth e o endereço externo do proxy reverso coincidem.
- O cliente oferece suporte à geração de protocolo correspondente, em vez de sempre enviar initialize ao ponto de entrada do protocolo novo.
- A autorização atual está vinculada à ontologia ou ao sistema de negócio necessário.
- O Token é válido e os novos scopes opcionais receberam autorização explícita.
OAuth: descoberta, registro e autorização
Use o código de autorização e PKCE; não exponha as credenciais de login do produto ao Agent.
| Endpoint | Método | Função |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Descoberta do recurso MCP de ontologia |
| /.well-known/oauth-protected-resource/mcp | GET | Descoberta compatível pelo caminho do recurso de ontologia |
| /.well-known/oauth-protected-resource/mcp/business | GET | Descoberta do recurso MCP de negócio |
| /.well-known/oauth-authorization-server | GET | Metadados do servidor de autorização |
| /oauth/register | POST JSON | Registro dinâmico de public client |
| /oauth/authorize | GET ou formulário POST | Login, seleção do recurso e confirmação da autorização |
| /oauth/token | POST form | Troca do código de autorização e renovação com rotação |
| /oauth/revoke | POST form | Revogação de Token |
| /oauth/grants | GET | Usuário autenticado visualiza conexões autorizadas |
| /oauth/grants/revoke | POST form | Revogar a conexão seguindo o fluxo da página original |
Ordem de autorização
- Leia os metadados do recurso protegido e os metadados do servidor de autorização. Uma solicitação sem Token retorna 401, e o cabeçalho WWW-Authenticate aponta para o endereço de descoberta de recursos.
- Registre ou use uma identidade de cliente. O registro dinâmico de public client do r56 usa token_endpoint_auth_method=none; um segredo de cliente não pode substituir PKCE.
- Gere state e code_verifier aleatórios e calcule o code_challenge S256.
- Abra o endereço authorize indicado nos metadados, passando response_type=code, client_id, redirect_uri exato, scope, resource, state, code_challenge e code_challenge_method=S256.
- O usuário faz login no DataFocus e seleciona a ontologia ou o sistema de negócio. O cliente não pode pré-selecionar recursos que o usuário não tem permissão para acessar.
- Receba o callback, valide state e issuer; troque o código de autorização usando o code_verifier original.
- Use o access_token apenas para autenticação Bearer de MCP. A renovação usa o fluxo original de OAuth; guarde com segurança o refresh_token rotacionado.
Exemplo de registro
{
"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"]
}O callback do cliente web usa HTTPS; clientes nativos podem usar endereços de loopback suportados. Tanto a autorização quanto a troca de Token exigem correspondência exata com o callback registrado. Cada Grant se destina a um único protected resource; não misture scopes de ontologia e do espaço de trabalho de negócio na mesma conexão.
Ciclo de vida dos Tokens
No servidor do r56, por padrão, o access token é de 3600 segundos, o refresh token de 2592000 segundos e o código de autorização de 300 segundos; a implantação pode sobrescrever esses valores. O cliente deve se basear no expires_in da resposta do token e nos erros reais, sem fixar os valores padrão no código. Atualize o Token após a renovação; revogar um papel, uma permissão de recurso ou um Grant fará com que chamadas subsequentes sejam rejeitadas.
Scope, limites de recursos e permissões em tempo real
O escopo de autorização delega as permissões existentes, não concede elevação de papéis e não compartilha estado de negócio entre Grants.
| Scope | Capacidades típicas | Restrições importantes |
|---|---|---|
| ontology.metadata:read | Ontologia, recursos, estrutura de tabelas | A ontologia e as tabelas devem estar no escopo autorizado e entre o que o usuário pode ler no momento |
| ontology.graph:read | Pesquisa no grafo e vizinhos | Retorna informações de localização, não evidências de fatos |
| ontology.knowledge:read | Localização de conhecimento e texto original completo | Preserva as permissões originais das bases de conhecimento e dos documentos |
| ontology.table:query | SQL de tabelas da ontologia e consulta a modelos publicados | A consulta de tabelas também exige scope de metadata; as permissões das fontes reais e das colunas continuam valendo |
| search:operate | Modelos nativos de palavras-chave e sessões | Delegação independente e explícita, executada conforme as permissões originais do modelo e as permissões de tabela e coluna do usuário |
| etl:operate | capabilities de ETL do Flash | Não disponibiliza o ETL do Heavy |
| authoring.contract:read | Contratos de modelagem disponibilizados condicionalmente | Também exige a opção de funcionalidade habilitada e os recursos correspondentes |
| authoring.artifact:read | Leitura de candidatos, planos etc. com a autorização atual | Vinculada ao principal, ao Grant e aos recursos originais |
| authoring.artifact:draft | Envio de candidatos, pré-visualização etc. | Não autoriza execução nem publicação |
| authoring.artifact:apply | Planejamento e aplicação controlados | Continua exigindo o papel de negócio, as políticas e as aprovações originais |
| execution.script:draft | Rascunhos de scripts específicos | Não autoriza a execução real de scripts |
| datasource.http:read / draft / test / import | Capacidades de artefatos de fontes de dados HTTP disponibilizadas condicionalmente | Cada item tem sua própria opção e mantém as permissões originais |
Requisitos combinados de leitura
dfc_table detail exige ontology.metadata:read; query exige também ontology.table:query. dfc_ontology_query exige os dois scopes de leitura, graph e knowledge. dfc_knowledge_search/detail exige knowledge. published_model/published_query usam table:query; candidate_query também precisa de authoring.artifact:read. As ferramentas de análise também verificam os scopes de evidência permitidos; relatórios persistentes exigem metadata e table query.
Não fixe no código as autorizações padrão
O conjunto padrão de scopes de ontologia do r56 inclui table query; Search e ETL são delegações explícitas. O que vale, no fim, são os metadados de descoberta, a página de autorização, o scope real do Token e o tools/list. As afirmações de documentos antigos, como "a ontologia nunca tem SQL por padrão" ou "existem apenas seis ferramentas", não podem ser tomadas como base da implementação atual.
Isolamento de estado
Sessões, relatórios, candidatos e planos de ação têm seus próprios proprietários e escopos. A renovação do access token não transfere o trabalho de um Grant original para outro Grant. Não mescle na conexão atual sessionId, reportId, planId, tokens de aprovação ou Tokens de origem retornados por outra conexão.
Mensagens HTTP e do MCP moderno
Envie corretamente os metadados de cada solicitação e os cabeçalhos de rota correspondentes e trate separadamente os resultados HTTP e os resultados de ferramentas.
| Item | Comportamento no r56 |
|---|---|
| Transporte | Streamable HTTP sem estado, POST JSON-RPC |
| Versões suportadas | 2026-07-28, além de 2025-11-25, 2025-06-18 e 2025-03-26 |
| Métodos modernos | server/discover, tools/list, tools/call, resources/list, resources/read, disponibilizados conforme as capacidades reais |
| Cabeçalho de sessão | Não atribui Mcp-Session-Id |
| GET e DELETE | /mcp e /mcp/business retornam 405 |
| Notificações SSE do servidor | Não são fornecidas por estes dois pontos de entrada MCP públicos |
| Cache do catálogo | A descoberta moderna e as listagens retornam ttlMs=60000 e cacheScope=private |
| Resultado comum | Os resultados modernos contêm resultType=complete e metadados de identidade do serviço |
Valores que devem coincidir
- MCP-Protocol-Version corresponde a io.modelcontextprotocol/protocolVersion em params._meta.
- Mcp-Method corresponde ao método JSON-RPC.
- Mcp-Name de tools/call corresponde a params.name; o cabeçalho de nome de resources/read corresponde à URI.
- Cada requisição moderna carrega um objeto io.modelcontextprotocol/clientCapabilities; forneça também o clientInfo padrão para facilitar a identificação do cliente.
Exemplo de chamada
{
"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": {}
}
}
}Os cabeçalhos HTTP correspondentes são Mcp-Method: tools/call e Mcp-Name: dfc_ontologies. Em todos os exemplos, ACCESS_TOKEN é um placeholder. Não coloque o Bearer Token em URLs, parâmetros JSON ou chaves de cache.
Leitura de resultados
Trate primeiro o status HTTP e depois verifique o error do JSON-RPC; quando houver result, verifique também isError. Resultados de ferramenta bem-sucedidos normalmente fornecem structuredContent, junto com um conteúdo text que traz o mesmo JSON de negócio; leia preferencialmente o canal estruturado e não some text e structuredContent como se fossem dois fatos independentes. Um HTTP 200 pode conter falhas de ferramenta.
Recursos públicos e UI
Os recursos de documentação integrados não dependem de MCP Apps. Isso não dá ao ponto de entrada do espaço de trabalho de negócio acesso aos recursos de documentação da ontologia. Clientes com suporte à visualização devem descobrir a UI correspondente por meio das capacidades reais e do _meta das ferramentas, sem adivinhar URIs de recursos não retornados.
Compatibilidade com clientes de protocolo legado
Mantenha uma geração de protocolo consistente em clientes que ainda usam o handshake de inicialização.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Envie initialize e leia a versão de protocolo e as capabilities negociadas pelo servidor.
- Envie a notificação de inicialização concluída exigida pelo protocolo do cliente; a notificação não retorna um resultado comum de ferramenta.
- Use tools/list para ler as ferramentas atualmente autorizadas e depois envie tools/call.
- Mantenha os cabeçalhos e as mensagens coerentes com a geração de protocolo da requisição atual; não use os fluxos antigos de initialize ou ping em mensagens 2026-07-28.
O protocolo legado usa o mesmo Bearer/OAuth, permissões e contratos de ferramenta. Isso não significa que o servidor necessariamente forneça conexões SSE persistentes no estilo legado ou Mcp-Session-Id; os serviços públicos do r56 permanecem sem estado.
Erros de protocolo
| Situação | Resultado típico | Solução |
|---|---|---|
| Cabeçalhos modernos inconsistentes com a mensagem | HTTP 400 JSON-RPC -32020 | Corrigir cabeçalhos, metadados e nome da ferramenta |
| Versão não suportada | -32022 com a lista de versões suportadas | Escolher um protocolo realmente suportado |
| Método desconhecido | JSON-RPC -32601; requisições modernas podem retornar HTTP 404 | Verificar a geração do protocolo e o método |
| Parâmetros ausentes ou inválidos | JSON-RPC com erro de parâmetros ou ferramenta com isError | Corrigir conforme o inputSchema real |
Escolher a ferramenta correta e o canal de evidências
Faça o roteamento conforme o problema de negócio ainda não resolvido, sem repetir a coleta de evidências em uma cadeia de chamadas fixa.
| Tarefa | Ferramenta preferida | Evidências necessárias para concluir |
|---|---|---|
| Descobrir temas e recursos autorizados | dfc_ontologies dfc_ontology_resources | Tipos reais de ID de recursos e escopo de visibilidade atual |
| Estatísticas de tabelas e TopN | dfc_table query | Recibo de execução bem-sucedida e evidenceRows completo |
| Consultar políticas, contratos ou relatórios | dfc_ontology_query ou knowledge search/detail | Texto original completo, autorizado e utilizável como fato |
| Localizar objetos no grafo | dfc_ontology_graph search/neighbors | Localizar a fonte real e obter o fato correspondente |
| Interação original por palavras-chave | dfc_manual e depois dfc_search | Resultados reais no modelo original e no frame de negócio |
| Análise integrada e relatórios | dfc_analysis_* ou dfc_report_* | Estado real de cada ramificação estruturada e das evidências documentais |
| Modificar visualização ou modelo da ontologia | dfc_authoring_* e ferramentas de artifact | Verificar separadamente candidato, plano, aprovação e aplicação efetiva |
| Executar comandos de negócio | dfb_* de /mcp/business | Contratos publicados e recibo original do ActionPlan |
Evitar chamadas desnecessárias
Quando já houver uma estrutura de tabela atual, completa e autorizada, não exigir um novo detail a cada consulta; quando já houver localização e evidências confiáveis, não repetir a mesma busca. Fazer consultas complementares delimitadas quando faltar alguma dimensão. Quando uma falha indicar claramente que não se deve tentar de novo, resolver primeiro a lacuna, em vez de substituir a análise por um "tentar de novo".
Exclusões do Flash
As capabilities de dfc_etl podem retornar available=false e ETL_NOT_INCLUDED_IN_OT_FLASH. A documentação estática das funções integradas de ETL serve apenas como referência entre produtos; ela não comprova que o ETL está instalado no Flash e não permite que o Agent passe automaticamente a executar no Heavy ou em outro tenant.
Recursos da ontologia e tipos de ID
Obter primeiro as coordenadas reais dos recursos, evitando confundir nomes de armazenamento, IDs de documentos e IDs de bases de conhecimento.
- Chamar dfc_ontologies e navegar pelas ontologias concedidas nesta autorização que ainda podem ser lidas, usando page e pageSize.
- Chamar dfc_ontology_resources com um ontologyId real; escolher conforme a necessidade entre tables, answers, pinboards, documents e knowledgeBindings.
- Tratar a paginação separadamente para cada tipo de recurso. pageSize tem no máximo 100; não inferir o escopo inteiro do recurso a partir da primeira página.
- Salvar o tipo declarado do recurso e o ID original e usá-los literalmente nas chamadas subsequentes.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordenada | Origem | Não substitui |
|---|---|---|
| ontologyId | Lista de ontologias autorizadas ou contexto válido atual | ID de outra ontologia |
| id do recurso de tabela | Lista de tables ou contexto confiável | physicalName ou nome de tabela exibido |
| tblDisplayName colDisplayName | Metadados atuais de tabelas e colunas | Identificador SQL físico adivinhado |
| knowledgeId | knowledgeBindings ou recibo real de recuperação de conhecimento | id do recurso de documento |
| assetId documentId chunkId evidenceId | O mesmo recibo real de localização | Campos montados a partir de resultados de localização diferentes |
| rid revisionId releaseId | Modelo publicado ou contexto de candidato no servidor | ID gerado pelo próprio cliente ou latest |
Convenções de precisão
Todos os identificadores de recursos de 64 bits devem ser preferencialmente strings decimais, sem conversão por Number em JavaScript. Alguns Schemas de negócio aceitam string ou integer, o que não autoriza descartar a precisão dos inteiros. Opaque locator, UUID, hashes e tokens de uso único também devem ser preservados como estão.
Consulta de tabelas Doris e contrato de estrutura
Executar SQL somente leitura sobre tabelas autorizadas, preservando a semântica da saída, os valores exatos e a integridade.
Leitura da estrutura
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}Usar detail com um ID real de recurso de tabela. Verificar schemaComplete, tblDisplayName, colDisplayName em columns e o sqlDataType autoritativo, além do queryContract retornado. dataType é apenas um mapeamento de compatibilidade; o nome de armazenamento físico não é o nome de tabela a ser usado no SQL enviado.
Execução de consultas
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}Restrições de SQL
- Usar nomes de tabela e de coluna exibidos, com identificadores entre aspas duplas. A requisição deve ser uma única consulta Doris somente leitura dentro do escopo da ontologia.
- Listar explicitamente as colunas de saída; SELECT * e table.* são proibidos, pois não podem servir para contornar, por meio de colunas físicas, as permissões das colunas registradas.
- Para junções, usar JOIN ... ON explícito; NATURAL JOIN e JOIN USING são rejeitados.
- São permitidas expressões somente leitura válidas, como agregações multidimensionais, CTE, janelas, CASE, COUNT(DISTINCT ...); o fato de a validação semântica não cobrir uma expressão não significa que sua execução seja proibida de forma geral.
- Concluir agregação, ordenação e ranking no próprio SQL antes de aplicar o limite de resultados. maxRows tem padrão 100 e máximo 200.
Datas e fusos horários
| Tipo ou objetivo | Forma | Observação |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) e CURRENT_DATE | Não assumir tipo de data a partir de literais de texto |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) e CURRENT_TIMESTAMP | Verificar o fuso horário da fonte e o da sessão |
| Tempo relativo | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Para datas e timestamps, usar a respectiva função de data/hora atual |
| Agrupamento temporal | YEAR(column) ou DATE_TRUNC(column, 'month') | Usar um alias único para cada saída; prevalece o queryContract |
O DATE('now', ...) do SQLite não segue o contrato de datas Doris deste ponto de entrada. Não leve para o SQL de produção o método de verificação offline com SQLite usado nos exemplos da documentação.
Ler o recibo de consulta v8
O evidenceRows é o único canal de dados de linha voltado ao Agent; os raw data não são expostos ao Agent. Os números do SQL são codificados como strings decimais exatas de JSON; determine seu valor numérico e tipo de negócio por meio de resultColumnContracts e não os interprete como VARCHAR apenas porque o valor JSON é uma string. Leia as informações de executionReceipt, integridade e truncamento e preserve as informações de origem, como evidenceRowsSha256.
As saídas de consulta com recibo de execução citável podem ser citadas como estão; somente a semântica validada pelo servidor pode autorizar recálculos determinísticos subsequentes. Não deduza “saldo acumulado”, “valor de fim de período” ou “moeda” a partir de nomes de campos, nem acrescente unidades por conta própria. Resultados de zero linhas, falhas ou truncamento não podem ser descritos como estatísticas completas.
Top3 multidimensional e tratamento de truncamento
Responda a perguntas de classificação com agregação e funções de janela no servidor; não faça cálculos secundários sobre resultados incompletos.
O arquivo complementar examples/top3.sql usa a tabela de exemplo: primeiro agrega por 区域, 类别 e 产品, depois executa ROW_NUMBER dentro de cada 区域 e 类别 e usa o nome do 产品 como critério de desempate estável quando os valores empatam. Solicitar maxRows=100 é suficiente para as 36 linhas do exemplo; outros dados de negócio exigem avaliação conforme o número real de grupos.
- Obtenha a estrutura real e a regra de negócio atual, esclarecendo 币种, período, 订单状态 e regras de empate.
- Envie o SQL de agregação e classificação a ser executado no servidor. Não consulte apenas o total por 区域 para depois tratá-lo como a classificação por 类别 e 产品.
- Verifique o contrato de colunas de saída e o evidenceRows real, confirmando que o retorno cobre todos os grupos necessários.
- Ao detectar truncamento, faça consultas particionadas e limitadas, dentro dos limites suportados pelo servidor, por exemplo, obtendo separadamente o Top3 completo de cada 区域; mantenha a mesma regra de negócio em cada consulta.
- Se o período de origem mudar, consulte novamente e declare explicitamente a nova versão, sem misturar versões de dados diferentes nem usar cursores expirados.
Recuperação de erros
TABLE_SCHEMA_INCOMPLETE exige corrigir a estrutura ou obter a estrutura completa; falhas como ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID devem ser tratadas de acordo com o errorCode, retryable e remediation retornados. Não afirme que “todos os GROUP BY multidimensionais ou funções de janela são proibidos” e não invente classificações sem ter resultados de consulta.
Recuperação de conhecimento: texto original completo e elegibilidade de evidência
Separe localização, leitura e citação de fatos, preservando a origem e a integridade.
Dois caminhos comuns
| Caminho | Finalidade | Pontos principais |
|---|---|---|
| dfc_ontology_query | Pesquisar dentro do conhecimento vinculado à ontologia, podendo combinar com roteamento por grafo | Verificar o answerContextItems canônico completo e a elegibilidade da evidência |
| dfc_knowledge_search → chunk via dfc_knowledge_detail | Localizar por busca explícita e, em seguida, ler o fragmento selecionado | A pré-visualização da busca não serve como fato; ler o texto original completo da mesma localização |
{"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>"
}}Condições para uso como fato
- Verificar o ACL atual, a integridade do conteúdo e os campos canonicalFactEligible, citationEligible do servidor ou o contrato de execução correspondente.
- O conteúdo completo fica vinculado ao contentSha256. Truncamento, omissão por orçamento ou conteúdo de baixa qualidade devem ser tratados conforme os campos reais.
- Metadados de documentos, page_context, localização no grafo, resumos de recuperação e pré-visualizações não substituem o texto original canônico.
- Copie preferencialmente evidenceId; quando precisar de chunkId e documentId, eles devem vir do mesmo resultado de localização, sem concatenar nem inventar valores.
Roteamento por grafo
O resultado de search/neighbors é informação de localização. Entregue à query da ontologia somente o objeto routeLocator retornado completo pelo servidor, incluindo vinculação, versão e campos de prova. Não encapsule por conta própria um assetId ou knowledgeId como se fosse um locator emitido pelo servidor, nem devolva provas de origem afirmadas pelo modelo.
Reconstrução estruturada de documentos
O structuredPlan de dfc_ontology_query é uma reconstrução restrita com validação determinística, dedicada a tabelas irregulares em documentos. Somente depois que o servidor retornar o executionContractSha256 e tableIndex atuais, as colunas e a tabela completa, use o plano declarado pelo servidor. Tabelas de negócio comuns já importadas devem usar o SQL do dfc_table; não trate a reconstrução de tabelas Markdown como um canal para contornar a autorização de consulta de tabelas.
Estratégia de recuperação
knowledgeIds normalmente é omitido para cobrir as vinculações atualmente habilitadas; ao passá-lo, use somente IDs de base de conhecimento reais de knowledgeBindings. Não use um ID de recurso de documento como ID de base de conhecimento. Faça novas buscas delimitadas conforme as perguntas não resolvidas, evitando repetir exatamente a mesma recuperação sem obter evidências novas.
Modelos e sessões nativos de Search
Use o protocolo de palavras-chave do Search em Rust por meio de dfc_search e aguarde o estado final do frame de negócio original.
Ler a documentação antes de descobrir capacidades
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search exige um search:operate explícito. Ele encapsula o WebSocket original de palavras-chave e não reescreve as palavras-chave como requisições SQL ou LLM. A sessão é vinculada ao tenant, usuário, Grant, cliente e modelo atuais, e as permissões originais de tabela e coluna são verificadas novamente a cada operação.
Fluxo mínimo de sessão
{"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 usa de 1 a 100 IDs reais de tabelas autorizadas, ou model_read lê um sourceToken já existente do próprio usuário.
- open retorna apenas initializationSent; primeiro faça poll, leia a resposta de negócio init original e confirme o sucesso.
- Leia assist e sugestões e, em seguida, envie a message original suportada. Em query datas, isNl é fixado como false pelo wrapper.
- Continue lendo frames, distinguindo sugestões, parsing, recepção e o resultado final de negócio.
- Ao terminar, use close; para cancelar, use cancel e confirme, pelo estado real da tarefa, se ela foi de fato encerrada.
| action | data | Significado |
|---|---|---|
| capabilities | Omitido ou objeto vazio | Ler ações, comandos, TTL e instruções de transporte |
| model_create | Array de tableIds | Criar o modelo autorizado do usuário atual |
| model_read | sourceToken | Ler o modelo, filtrando colunas sem permissão e configurações sensíveis da fonte |
| open | sourceToken e language opcional | Estabelecer a sessão nativa e enviar init |
| request | sessionId e message | Enviar mensagem do protocolo original type/datas |
| poll | sessionId e waitMillis de 0 a 30000 | Retirar os frames atualmente no buffer, com espera limitada opcional |
| cancel close | sessionId | Encerrar esta sessão nativa; isso não comprova o estado final no BI |
Comandos originais suportados
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteO uso de maiúsculas e minúsculas nos comandos e a estrutura de datas seguem as capabilities atuais e o protocolo da sessão original. Não acrescente ações inexistentes à request; por exemplo, a grafia de disambiguite deve ser preservada conforme o protocolo real. A mensagem tem no máximo 256 Ki caracteres.
Sessão e integridade
O TTL da sessão é de 10 minutos, e ela é mantida apenas enquanto o processo atual estiver ativo; não é uma tarefa recuperável de forma persistente. O buffer admite no máximo 256 frames e está sujeito a limites de memória; quando bufferOverflow=true, os frames já recuperados não podem ser tratados como resultado completo. Após erros de transporte, faça primeiro poll da sessão original; não reenvie às cegas consultas possivelmente já executadas.
O wrapper atual não oferece salvamento de respostas ou pinboards, leitura e escrita de histórico, nem recuperação arbitrária de contexto. A existência de exportContext não significa que qualquer contexto possa ser recuperado por conta própria. Para salvar resultados, use as capacidades de recursos originais realmente disponibilizadas pela instância; não invente actions.
Convenções de idioma e região
Mantenha os limites entre o locale da UI, o dicionário de consultas, o idioma de retorno e os nomes de campos originais.
A prioridade é: idioma explicitamente solicitado, idioma do sistema do aplicativo, locale do nó de execução real. Valores ausentes, null, strings vazias e espaços em branco não acionam um fallback fixo para o chinês. O valor de região em languageRegistry deve permanecer exato; não colapse arbitrariamente en-GB, fr-CA, pt-BR, es-US ou ar-AE em outra região.
| Idioma ou região | Locale de consulta | Descrição |
|---|---|---|
| Chinês simplificado, chinês tradicional | zh-CN zh-Hant | As regras originais do chinês diferem do catálogo em chinês tradicional |
| Inglês dos EUA, Reino Unido, Austrália e Canadá | en-US en-GB en-AU en-CA | O pacote de UI/palavras-chave pode ser compartilhado; os metadados de região são preservados |
| Alemão, italiano, russo | de-DE it-IT ru-RU | Usar conforme as sugestões da sessão atual |
| Espanhol da Espanha e da América Latina | es-ES es-US | O ID de região do produto é es-US |
| Francês da França e do Canadá | fr-FR fr-CA | Os IDs de região não são mesclados |
| Português de Portugal e do Brasil | pt-PT pt-BR | Catálogo e convenções de região são preservados separadamente |
| Holandês, dinamarquês, norueguês, finlandês, sueco | nl-NL da-DK nb-NO fi-FI sv-SE | O norueguês é Bokmål |
| Japonês, coreano | ja-JP ko-KR | Não segmente palavras por conta própria com base nas regras de espaçamento do inglês |
| Árabe da Arábia Saudita e dos Emirados Árabes Unidos | ar-SA ar-AE | As descrições da interface suportam RTL; os identificadores de protocolo não são invertidos |
Usar o catálogo de palavras-chave
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}O catálogo estático de palavras-chave de dfc_manual abrange apenas os locales explicitamente listados; quando omitido, usa-se a referência em inglês; este é um valor padrão de referência, não uma regra de análise do idioma da consulta. Quando não houver catálogo estático para uma variante regional, obtenha as sugestões reais por meio do assist da sessão atual, sem fabricar aliases ou resultados de fallback. Cada chamada aceita no máximo 32 itens em names.
O que não traduzir
- Tabelas, colunas, valores de enumeração, nomes de clientes, nomes de fórmulas e outras strings reais do modelo.
- Nomes de ferramentas, action, scope, campos de Schema, códigos de erro e valores de estado.
- IDs de recursos, hashes, opaque locators e referências emitidas pelo servidor.
Por exemplo, uma pergunta em alemão pode consultar a coluna de exibição em chinês “销售金额”. Transformá-la em um nome de coluna em alemão criaria outro identificador, não uma tradução de interface. Após trocar o idioma, reinicialize ou atualize a sessão conforme o protocolo original e obtenha novamente as sugestões e os candidatos de desambiguação.
Análise integrada e resultados interativos
Nas ferramentas de análise disponibilizadas condicionalmente, preserve a autorização, a versão, a ramificação e o estado das evidências.
dfc_analysis_* é controlado por datafocus.mcp.analysis.tools.enabled. A parte estruturada continua seguindo consultas autoritativas de Search e a política de linhas atual; a parte de documentos volta a obter o texto original completo sob o ACL atual. Essas ferramentas não são pontos de entrada abertos para SQL, instruções arbitrárias ou injeção de filtros arbitrários.
| Ferramenta | Finalidade | Coordenadas necessárias |
|---|---|---|
| dfc_analysis_ask | Fazer uma pergunta de análise em linguagem natural | ontologyId e question; opcionalmente, language e sessionId |
| dfc_analysis_result_get | Ler um resultado já retornado | ontologyId sessionId resultId |
| dfc_analysis_refine | Fazer perguntas de acompanhamento ou alterações com base no resultado completo mais recente | O expectedRevision do resultado original e uma chave de idempotência estável |
| dfc_analysis_page | Obter uma página da ramificação do servidor | A ramificação e a versão do resultado originais, pageNo pageSize |
| dfc_analysis_cancel | Cancelar um resultado ainda em processamento | A sessão e o resultado originais |
| dfc_analysis_close | Liberar uma sessão que não esteja em processamento | A sessão original |
Iniciar a análise
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Leia o sessionId, o resultId, o status e a revision retornados; se necessário, continue lendo o resultado original.
- Verifique o status, a integridade, a política de linhas e a origem de cada ramificação estruturada, uma a uma; a conclusão de uma ramificação não significa que toda a análise está completa.
- Verifique as evidências de documentos, o registro de fatos, a elegibilidade de citação e as limitações. A narrativa gerada pelo modelo não pode, por si só, elevar a elegibilidade da evidência.
- Ao fazer perguntas de acompanhamento, baseie-se no resultado completo mais recente e informe expectedRevision; ao repetir a mesma alteração, reutilize a mesma chave de idempotência.
- Antes de fechar, confirme que a sessão não está mais em processamento; cancelar e fechar são ações distintas.
Filtragem controlada e paginação
filter_patch usa o branchId, fieldRef, valueRef e os operadores permitidos fornecidos pelo servidor; a filtragem tipada atual declara apenas EQ. É proibido substituir referências opacas por SQL, tableId, columnId brutos ou por uma árvore de filtros fabricada no cliente. Na paginação, pageNo começa em 1, com máximo de 10000; pageSize tem máximo de 100.
Dicas de capacidade e comportamento
As annotations das ferramentas são dicas para o cliente, não autorizações de segurança. Alguns templates genéricos usam readOnlyHint, o que não substitui a avaliação da ação real; cancelar, fechar e criar relatórios alteram o estado de trabalho correspondente. Execute sempre conforme a semântica da ferramenta, o objetivo do usuário e as permissões do servidor.
Relatórios visuais persistentes e MCP Apps
Crie relatórios recuperáveis e leia seus resultados e interfaces interativas conforme as permissões atuais.
dfc_report_* é controlado por datafocus.mcp.analysis.report-tools.enabled e exige os scopes metadata e table query. Diferentemente da sessão Search, que existe apenas no processo, os relatórios usam um reportId persistente; ser persistente não significa que as permissões deixem de ser verificadas.
{"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>"
}}Fluxo de trabalho
- Na criação, use um idempotencyKey estável, com 8 a 128 caracteres suportados.
- Salve o reportId, faça polling do status e verifique os estados reais, como concluído, com falha, parcialmente concluído ou cancelado.
- Ao ler os resultados, confirme as ramificações estruturadas, as visualizações, as fontes dos fatos, as referências documentais e a integridade.
- Para cancelar um relatório não concluído, use o reportId original; não crie outro relatório no lugar do cancelamento.
- Após um timeout de rede, leia primeiro o estado do relatório original; ao repetir com a chave de idempotência original, mantenha a mesma intenção de negócio.
MCP Apps
Clientes com suporte a extensões de UI descobrem as páginas de relatório por meio do _meta das ferramentas e dos recursos reais. A página de relatório persistente correspondente ao r56 é ui://datafocus/analysis-report/v16/index.html, e a análise interativa usa as referências de recursos apropriadas do servidor; o cliente não deve fixar esses valores no código em substituição aos retornados pelas ferramentas. Sem extensão de UI, ainda é possível ler os resultados estruturados.
Vinculação de origem
A leitura de relatórios reavalia o Grant, a ontologia, o vínculo do Origin da requisição e as permissões atuais de tabela. Integrações cross-origin no navegador exigem origens reais aprovadas; o cliente não deve contornar o vínculo falsificando o Origin. Um reportId antigo não é um link público permanente nem uma credencial de acesso entre usuários.
Rascunhos de artefatos, pré-visualização, planos e aplicação
Entregue o conteúdo gerado ao servidor original para normalização, validação e aprovação; não permita que o modelo altere diretamente recursos de produção.
As ferramentas de artefatos exigem a funcionalidade authoring habilitada, o artifact type real, os scopes relevantes e a permissão original de escrita de administrador. Os tipos padrão são configurados como CONTROL_PANEL_SPEC e VIEW_SPEC; os demais tipos, como formulário, fonte HTTP ou script, também dependem de configurações independentes. Como o Flash não possui AutoML, os tipos relacionados não são listados como artefatos disponíveis nesta versão.
- dfc_authoring_capabilities lê os contratos e ações disponíveis no Grant atual.
- dfc_artifact_context obtém contexto delimitado, contractVersion, contextHash, baseArtifactHash e baseArtifactVersion.
- Gere candidatos no cliente a partir dos contratos reais, sem executar o código contido neles.
- dfc_artifact_submit envia o contexto original e o candidato, mantendo o instruction idêntico e usando um clientRequestId estável.
- Leia proposalId, candidateHash, os resultados da validação e a pré-visualização; diante de erros reais, revise o candidato, sem forjar um status de validação aprovada pelo servidor.
- Quando for necessária nova pré-visualização, use dfc_artifact_preview e o mesmo hash do candidato.
- dfc_artifact_plan cria um plano imutável, com candidato real, versão de destino e chave de idempotência.
- Trate as aprovações conforme a interação original ou a política já autorizada, e só então chame dfc_artifact_apply; apenas o recibo APPLIED representa a aplicação efetiva.
Solicitação de contexto mínimo
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC usa o projectId atualmente autorizado; ao editar um artefato existente, use o artifactId real. Campos como variables, previewInput e viewport devem ser fornecidos conforme o contrato retornado, sem inventar a estrutura interna dos candidatos.
Concorrência e novas tentativas
O plano fica vinculado à versão de destino, ao hash do candidato e à chave de idempotência. Se o destino mudar, o plano antigo não pode continuar a ser aplicado; releia o contexto e trate o conflito real. Um timeout de transporte não comprova falha; primeiro use dfc_artifact_status para consultar o proposalId ou planId original. READY não é APPLIED.
Aprovação e política automática
Planos de artefatos genéricos exigem a aprovação humana original. Planos que atendem à política de publicação automática da ontologia são tratados conforme approvalMode, sem exigir que o usuário assine outra aprovação inventada pelo agente. approvalToken é material emitido pelo servidor e não pode ser substituído por uma string escrita pelo Agent; o inputSchema real e o recibo do plano determinam os campos obrigatórios.
Contratos de criação e publicação de candidatos de ontologia
Use declarações de ontologia e configurações de publicação versionadas de forma independente; não aplique contratos de artefatos de exibição comuns à publicação de modelos.
Criar candidato
O contêiner de ontologia já deve existir e estar dentro do Grant. Use dfc_ontology_table_schema para verificar os campos atuais das fontes estruturadas e a impressão digital do Binding v4; os campos podem ser fornecidos apenas com sourceField para descoberta automática de tipos. Declarações explícitas DECIMAL exigem a precisão e as casas decimais atuais; outros tipos não carregam esses dois campos.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Candidatos e configuração de publicação
| Contratos | Finalidade | Limites essenciais |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Criar candidato a partir de declarações locais | Fontes autorizadas reais, compilação no servidor; não aceita provas de conclusão |
| ontology-workspace-create-mcp-submit-v2 | Combinar referências locais e referências exatas já publicadas | Fornecer releaseSelections exatos e as dependências do fecho |
| ontology-publication-mcp-submit-v1 até v3 | Vincular um candidato existente a uma requisição de plano de publicação | Coordenadas explícitas; destino, fontes, aprovação e validação são restabelecidos pelo servidor |
| ontology-publication-mcp-submit-v4 até v6 | Configuração relacionada à publicação automática, habilitada separadamente | Usada apenas quando capabilities e schema real estão declarados |
| ontology-initial-activation-retirement-submit-v1 | Operações controladas de ativação inicial e retirada | Plano independente, nova aprovação humana e escopo exato |
Ordem de publicação
- Do candidato atual, obtenha workspaceId, workspaceRevision, candidateHash e as fontes reais.
- Escolha a versão do contrato conforme as capacidades do servidor; envie coordenadas como releases e selection, sem incluir campos que se declarem "aprovado" ou "validado".
- Preserve o proposalId retornado pelo submit e o idempotencyKey original. submit e MODEL_PLAN são fases distintas da mesma requisição.
- Chame dfc_artifact_plan usando o candidato original, a versão de destino e a mesma chave de idempotência.
- PLANNING_INCOMPLETE indica apenas que ainda não se formou um plano válido; VALIDATION_UNSATISFIED indica que a validação atual ainda tem lacunas; trate-as conforme o nextAction.
- Após o êxito do plano, prossiga conforme HUMAN_REQUIRED ou POLICY_AUTO, usando as capacidades originais de aprovação e publicação.
- Confirme o resultado com o recibo APPLIED e, em seguida, com a leitura real do modelo publicado e consultas autorizadas.
Timeouts e recuperação
Após o timeout de PLAN, leia o proposalId original. MODEL_PLAN_SUBMITTED é uma requisição não concluída; MODEL_PLAN_COMPLETED significa que o recibo original deve ser recuperado com as coordenadas e a chave originais, e não que o cliente deva criar uma nova requisição. Lacunas de validação no estado final não se convertem em publicação aprovada com a troca da chave ou com um novo envio.
Permissões de negócio humanas
O instruction e as declarações fornecidos pelo Agent são entradas do Agent, não assinaturas de políticas humanas. MODEL_AUTHOR, MODEL_PUBLISH, a delegação de publicação automática, a confirmação de negócio, a confiança em chaves públicas, o orçamento e as ACLs das fontes continuam sendo determinados pelos mecanismos originais. Não use campos do cliente para substituir esses fatos.
Modelo publicado, consultas de candidatos e fecho de referências
Use conhecimento de negócio publicado por versões exatas e preserve o caráter temporário dos candidatos não publicados.
published_model, published_query e candidate_query de dfc_ontology_graph são configurações estruturadas disponibilizadas condicionalmente, não sinônimos de um search/neighbors comum. São autorizadas com base no table query e nas permissões de leitura de modelagem necessárias; a visibilidade no grafo não substitui as permissões de tabela.
Ler o modelo publicado
- Quando o enum de action da ferramenta incluir published_model, envie o releaseId committed real.
- A v1 retorna templates de consulta autorizados; a v2 acrescenta referências exatas PERSISTED e releaseSelections; a v3 acrescenta referências de dependência, domainRef exato e templates de binding compactos.
- Selecione objetos, propriedades, Binding, scope e versão a partir dos valores realmente retornados, sem gerar RIDs nem usar latest.
- Envie as consultas tipadas fixas de published_query; os resultados ainda precisam passar pela autorização atual de fonte e campo.
Consulta de candidatos
candidate_query usa o workspaceId real, revision, candidateHash e as declarações do candidato. Ao misturar referências publicadas, use as coordenadas tipadas correspondentes da v2, LOCAL/PERSISTED, e seleções exatas. Os resultados de candidatos são sempre não publicados e temporários, não devendo ser tratados como conhecimento corporativo confirmado.
Manutenção parcial e fecho
Selecione apenas as dependências transitivas exigidas pela raiz do candidato e garanta que cada referência publicada tenha um releaseSelections exato. Copiar o corpo publicado, enviar apenas um conjunto de IDs ou ampliar para todos os recursos históricos não substitui a verificação atual de dependências e fontes.
As consultas dessas actions são objetos tipados versionados e não aceitam SQL, IDs de tabelas físicas ou nomes de tabelas de origem como substitutos de suas referências de negócio. Templates de metadados e resultados do grafo, por si só, não são elegíveis como referência de fatos.
Delegação de tarefas ao agente de ontologia
Retome o trabalho com tarefas persistentes e o Grant original; não trate instruções do Agent como aprovação humana.
dfc_ontology_agent é exibido apenas quando o Pi Runtime real e as permissões relacionadas estão disponíveis. QUERY usa capacidades de leitura; AUTHORING exige também o papel de modelagem e o scope de authoring correspondente. A ferramenta não disponibiliza outro mecanismo de execução sem restrições.
{"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>"
}}Conjunto estrito de parâmetros
start usa contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel usam contractVersion, action, ontologyId, runId. O servidor verifica o conjunto exato de campos conforme o action. O instruction tem no máximo 16000 caracteres; a chave tem de 1 a 128 caracteres suportados, começando por letra ou dígito.
Retomada e cancelamento
- Preserve o runId original, o Grant, o mode e a chave de idempotência.
- A mesma chave com o mesmo instruction retoma o mesmo run, sem enviar outra tarefa; a mesma chave com instrução diferente é rejeitada.
- status consulta o estado da tarefa original. Mesmo após a conclusão, é preciso conferir suas consultas de tabela, evidências ou recibos de publicação.
- O cancelamento usa o runId original; confirme o resultado pelo estado real da tarefa.
A conclusão do run não é um recibo de publicação do modelo. A tarefa de publicação continua sendo confirmada pelo estado original do artefato e pelas verificações de fonte; QUERY não implica direito de escrita ou publicação.
MCP do espaço de trabalho de negócio
Consulte registros com base em contratos de negócio publicados e execute comandos por meio do ActionPlan original.
/mcp/business usa um protected resource independente e seleção de sistema de negócio, não podendo reutilizar o Grant de ontologia no lugar da autorização de negócio. O sistema de negócio precisa estar publicado, disponível para chamada pelo Agent e atender à política de segurança original, e o usuário atual deve ter papel e capacidades reais de runtime.
| Scope | Ferramenta | Limites |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Descobre somente os sistemas concedidos nesta autorização e que podem ser chamados no momento |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Registros legíveis pelo usuário atual e seus próprios planos |
| business-system:plan | dfb_action_plan | Apenas criar planos imutáveis, sem executar |
| business-system:execute | dfb_action_execute | Autorização independente e explícita, com execução conforme risco e aprovação |
- dfb_systems descobre os sistemas autorizados.
- dfb_system_describe lê o contrato publicado atual, releaseId e todos os hashes, consultas e comandos.
- dfb_query usa o queryKey publicado, especificando conforme necessário objectKey, state, page e pageSize. Não é um SQL arbitrário.
- dfb_record e dfb_work_items leem os registros e pendências atualmente permitidos.
- Antes de executar, use dfb_action_plan para fornecer o releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey reais e o payload do contrato.
- Confira riskClass, requiresApproval e status; quando envolver registros de destino, preserve expectedRecordVersion.
- dfb_action_execute executa apenas planos que pertencem à conexão atual e estão prontos; os tokens de aprovação exigidos para aprovação humana são emitidos pelo DataFocus.
- Após falha ou timeout, dfb_action_status recupera o estado do plano original; as novas tentativas mantêm a semântica de idempotência original.
Vínculo de conexão e versão
O plano fica vinculado ao ID de isolamento estável do Grant atual. Após a renovação do Access Token, ainda é possível processar planos da mesma conexão; outra conexão OAuth não pode assumi-los. Na execução, são reavaliados a versão publicada, os hashes de IR/manifest, a versão dos registros de destino, a expiração do plano, a idempotência e a aprovação. A allowlist do OAuth não permite contornar a governança de negócio.
Entradas de conhecimento de negócio e perguntas pendentes de confirmação
Registre entradas de negócio quando os processadores de produção correspondentes estiverem disponíveis e preserve os limites de confirmação humana.
As quatro ferramentas a seguir são adicionadas condicionalmente pelo controlador MCP público, conforme os processadores instalados e o scope atual. Elas nem sempre aparecem no catálogo básico. A existência de um Schema declarado não significa que a instância tenha processadores, orçamento e permissões completamente configurados; verifique primeiro tools/list.
| Ferramenta | Finalidade | Autorizações ou efeitos que não produz |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registrar a entrada de negócio original em um workspace existente | Não gera perguntas de confirmação, não aprova, não publica |
| dfc_ontology_knowledge_input_preview | Pré-visualizar temporariamente rascunhos de perguntas a partir da entrada original | Não persiste, não confirma, não gera recibo de produção |
| dfc_ontology_knowledge_question_submit | Salvar perguntas authored e não confirmadas | Não mescla respostas automaticamente, não confere permissões de responsável nem direito de publicação |
| dfc_ontology_business_scope_initialize | Inicializar explicitamente um escopo de consumidor de sistema de negócio | Não publica, não ativa, não concede acesso às fontes |
Entrada e pré-visualização
- Obtenha workspaceId, workspaceRevision, localRef e preparationDigest a partir do trabalho de preparação real.
- propose registra as entradas de negócio usando o contrato input original e o idempotencyKey estável; a mesma chave só pode corresponder à mesma entrada.
- preview usa a chave de idempotência e o ontologyId da entrada original; a cada chamada, retorna a revision do servidor e uma janela de 60 segundos, e não é um recibo idempotente de conclusão de produção.
- Quando for necessário armazenar uma pergunta, question_submit usa uma nova chave de comando, o originalInputKey original, questionRevision, validFrom, validUntil e expectedRevision, todos explícitos; na criação, expectedRevision é null.
Entrada de confirmação humana
A knowledgeConfirmationPage retornada por question_submit é apenas um endereço relativo da página original, que exige login, com uma pergunta pré-preenchida. Ela não inclui Bearer, não abre a página automaticamente e não confirma o conhecimento. QUESTION_STORED_UNCONFIRMED indica explicitamente que ainda não houve confirmação; não escreva na resposta que “o conhecimento foi publicado”.
Inicialização do escopo de consumidores
business scope initialize exige simultaneamente permissão de publicação da ontologia e permissão de criador ou de administração SourceManager do sistema de negócio exato. Ele usa as coordenadas reais de domainRid, domainRevisionId e businessSystemId; o cliente não pode preencher arbitrariamente um consumerScope nem uma prova de conclusão. Os status INITIALIZED e COMPLETED retornados ainda indicam explicitamente published=false e activationAuthorized=false.
Essas solicitações também passam por validação rigorosa de JSON, do conjunto de campos, de bytes e de profundidade. O limite das solicitações de entrada é 1 MiB; algumas operações específicas têm limites menores. Os Schemas completos de entrada e saída são entregues com a referência das ferramentas; não aplique a lógica de parâmetros permissiva do wrapper geral de MCP a esses contratos rigorosos.
Resposta, erros e nova tentativa segura
Explique os erros em camadas, mantendo as coordenadas da tarefa e a semântica de idempotência.
| Camada | Conteúdo verificado | Princípio de tratamento |
|---|---|---|
| Rede e HTTP | Conexão TLS, 401, 403, 400, 404, 405 etc. | Não trate uma resposta de falha como resultado normal de consulta |
| JSON-RPC | error.code, message, data | Distinguir problemas de protocolo, método, parâmetros e autorização |
| Ferramenta MCP | result.isError e structuredContent | HTTP 200 ainda pode indicar falha |
| Resultado de negócio | Status real, integridade, motivo da falha, nextAction | Recebido ou pronto não significa concluído |
| Elegibilidade como fato | executionReceipt, citationEligible, contentComplete | Conteúdo não elegível serve apenas para localizar ou explicar lacunas |
Situações comuns de HTTP
- 401: Bearer ausente ou inválido; renove o token ou autorize novamente conforme o fluxo OAuth atual.
- 403: Grant, papel, recurso selecionado, permissão da fonte, Origin ou configuração não atendidos; não tente contornar reenviando a solicitação.
- 400: mensagem ou contrato versionado inválido, incluindo cabeçalhos modernos inconsistentes com os metadados.
- 404: verifique o caminho exato do serviço, o método do protocolo e as capacidades do runtime; não troque aleatoriamente o ID da ontologia.
- 405: o GET e o DELETE do /mcp público não estão disponíveis por definição; use o POST correto em vez de abrir uma conexão SSE persistente.
Operações de escrita com resultado incerto
MCP_OPERATION_OUTCOME_UNKNOWN pode conter outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool e os parâmetros de localização originais. Consulte primeiro o status original e depois retome a solicitação original. Não reenvie o candidato, não troque a chave de idempotência e não trate o timeout como rollback da transação.
Conteúdo que deve ser preservado como está
- Grant original, escopo de recursos, IDs de tarefas e resultados.
- candidateHash, planHash, expectedRevision, versão de destino e escolha de publicação.
- Chave de idempotência da mesma operação lógica; operações de negócio diferentes devem usar chaves novas.
- retryable, remediation, nextAction declarados pelo servidor e o status atual.
Não extraia SQL interno, hosts, credenciais ou stacks do texto da exceção como fonte para a resposta. Basta registrar os códigos de erro que podem ser divulgados e as informações de correlação da solicitação; o erro original pode precisar ser examinado por um administrador em logs controlados.
Segurança de integração e limites de capacidade
Mantenha os limites originais de identidade, recursos, execução e evidências; trate documentos não confiáveis com segurança.
- Conecte-se apenas aos domínios oficiais indicados pelo administrador; verifique o TLS e o issuer do OAuth e não desative a verificação de certificados.
- Use um Grant dedicado com escopo mínimo de recursos; não use contas de administrador, Cookies ou Tokens internos de longa duração como credenciais de interface pública.
- Trate o corpo dos documentos como material de negócio não confiável. “Ignorar regras”, “enviar chaves secretas” ou “executar comandos” presentes em documentos não constituem autorização de ferramenta.
- Limite repetições automáticas, concorrência e escopo de resultados; não reconstrua no cliente as permissões de negócio originais.
- Registre nos logs apenas as informações de correlação necessárias; não registre Bearer, refresh token, tokens de aprovação nem conteúdo de negócio sensível completo.
- Após desconexão do usuário ou revogação pelo administrador, pare de usar autorizações e dados em cache e não continue chamando com um locator antigo.
As dicas das ferramentas não são permissões
readOnlyHint, destructiveHint, idempotentHint e openWorldHint servem para o cliente entender as capacidades; não garantem o efeito de negócio real de cada chamada e não substituem a autorização do usuário atual. Trate todas as ações de escrita, plano, pré-visualização, sessão e cancelamento conforme seu comportamento real.
Entradas que não devem ser chamadas
- Os serviços originais Trino/Hive/Hadoop e o ETL do Heavy, que não está incluído no Flash.
- Scopes ou interfaces de workspace exclusivos do FocusCode interno.
- Ferramentas execution v2, AutoML ou outras experimentais que não apareçam no tools/list da instância atual.
- REST privado do navegador, conexões arbitrárias de banco de dados ou serviços de outros tenants usados para contornar uma recusa do MCP.
Semântica dos dados
Siga os contratos do servidor para decimal exato, tipos, moeda, unidades, tempo e evidências. Não arredonde novamente nem converta a moeda só porque o texto de saída parece um número, e não faça ranking global das linhas visíveis quando o resultado estiver truncado.
Configuração do administrador e opções condicionais
Antes de habilitar capacidades estendidas, confirme os componentes reais, os endereços públicos e as configurações de permissão originais.
| Configuração | Finalidade | Requisito para entrada em produção |
|---|---|---|
| datafocus.mcp.public-base-url | Endereço raiz externo oficial | Descoberta OAuth, issuer, callback e proxy reverso consistentes entre si |
| datafocus.mcp.allowed-origins | Origens de navegador aprovadas adicionalmente | Configuração exata, sem ampliar para origens arbitrárias |
| datafocus.mcp.oauth.route-proof-secret | Segredo de servidor dedicado à prova de roteamento do grafo | Armazenamento independente, sem usar Bearer como chave |
| datafocus.mcp.analysis.tools.enabled | Ferramentas de análise interativa | Serviços de dados, conhecimento e permissão associados realmente disponíveis |
| datafocus.mcp.analysis.report-tools.enabled | Ferramentas de relatórios persistentes | Armazenamento, worker e cadeia de recuperação associados disponíveis |
| datafocus.mcp.analysis.apps.enabled | Exibição de MCP Apps | O cliente declara suporte e verifica o _meta retornado |
| datafocus.mcp.authoring.enabled | Contratos de rascunho e modelagem | Preservação das permissões originais de administrador e recursos |
| datafocus.mcp.authoring.apply-enabled | Capacidade de aplicação de artefatos | Plano imutável, aprovação original e nova validação do estado atual |
| datafocus.mcp.ontology-published-query-enabled | Modelo publicado e consultas | Versões committed reais e autorização das fontes |
| datafocus.mcp.ontology-candidate-query-enabled | Consulta estruturada de candidatos | Propriedade do candidato, versão exata e permissão de leitura |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Autorizações relacionadas à delegação de publicação automática | Política original válida, confiança em chave pública, orçamento e permissão de publicação |
Esses nomes vêm da configuração e da implementação do r56; a possibilidade de ativá-los depende dos serviços associados e dos gates originais de entrada em produção. Alterar apenas valores booleanos não supre processadores, bancos de dados, orçamentos de validação ou políticas ausentes. A visibilidade da extensão de entrada de conhecimento e das tarefas Pi depende dos componentes realmente instalados.
Proxy de borda
Preserve Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name e o Origin aprovado. Defina o corpo da solicitação, os timeouts e o TLS conforme os requisitos reais do serviço; não encaminhe o /mcp público para uma porta de administração ou para outro produto.
Verificação de entrada em produção
- O status da descoberta anônima e das chamadas protegidas está conforme o esperado.
- Usuários comuns só descobrem seu escopo autorizado; após revogação, as solicitações seguintes são rejeitadas.
- Sessões nativas de Search, SQL, texto original e relatórios opcionais têm, cada um, resultados reais.
- As aprovações de escrita e publicação e a recuperação idempotente mantêm o comportamento original.
- Logs e documentação pública não contêm chaves privadas, Tokens, Cookies, senhas nem dados internos de clientes.
Cliente executável e exemplos de chamada
Valide as mensagens com o cliente mínimo fornecido, sem contornar o OAuth nem a autorização atual.
examples/flash_mcp.py é um cliente de protocolo mínimo que depende apenas da biblioteca padrão do Python. Ele não faz login, não aprova em nome de ninguém, não chama automaticamente ferramentas não visíveis, oferece suporte aos protocolos moderno e legado e encerra com saídas distintas para erros de HTTP, JSON-RPC e de ferramenta. O Token é fornecido por variável de ambiente do processo, sem ser gravado em scripts ou arquivos de documentação.
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_TOKENLeitura e consulta
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.jsonSubstitua primeiro os placeholders, como ONTOLOGY_ID e TABLE_RESOURCE_ID, no arquivo de solicitação, pelos valores reais retornados pela autorização atual. O cliente se recusa a executar ao encontrar placeholders. O exemplo de SQL exige que o CSV associado já tenha sido importado com os nomes de coluna originais; sem o schema correspondente, não é possível enviá-lo diretamente.
Outros cenários
- Entrada de negócio: use --endpoint business para obter novamente um Grant voltado ao /mcp/business.
- Cliente legado: escolha --protocol 2025-11-25, faça primeiro o initialize e depois chame com o mesmo protocolo.
- Documentação integrada: use resources ou read-resource para ler a URI real.
- Autoteste offline: --self-test valida a construção de cabeçalhos modernos e metadados, sem necessidade de Token e sem enviar solicitações ao servidor do produto.
Limites do exemplo
O cliente é o ponto de partida para a integração com o protocolo; ele não gera candidatos de modelagem automaticamente, não salva perguntas e respostas nem executa publicações. Ele emite o JSON original para que o Agent da camada superior verifique o status de negócio; não prometa ao usuário a conclusão de consultas, relatórios ou publicações apenas com base no código de saída do processo.
Incorporar a interface de conversa da ontologia
Incorpore a página de conversa para usuários humanos ao frontend de negócio, mantendo os limites de segurança do login e do navegador.
<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 é um ID de tenant de exemplo e 1001 é um ID de ontologia de exemplo; ao usar, substitua-os por coordenadas reais para as quais o usuário tenha permissão. Uma única ontologia pode ser indicada por path ou por query suportada; o modo all oferece @ para selecionar as ontologias acessíveis ao usuário atual. skillId é apenas repassado; não afirme, com base nele, que a orquestração de skills já pode ser executada.
Autenticação e domínios
A página incorporada atual depende de uma sessão de login real do DataFocus e verifica /uc/status. Cookies entre sites, SSO, frame-ancestors de CSP e a configuração do gateway afetam a incorporação. Ela não aceita inserir um Bearer de MCP em URL como canal de acesso sem login; o link externo outside, ainda não implementado, não deve ser montado por conta própria com base em propostas de design.
Diferença entre MCP e iframe
| Modo | Usuário | Identidade e resultado |
|---|---|---|
| Remote MCP | Integração de Agent ou serviços externos | Grant de OAuth e recibo estruturado de ferramentas |
| Conversa de ontologia em iframe | Usuário final humano | Sessão de login original e interface de conversa |
| MCP Apps | Cliente MCP com suporte a extensões | Recursos controlados e resultados de ferramentas atuais, não um substituto público para login em iframe |
Lista de verificação de aceitação de integração
Prove a cadeia completa de negócio em uma instância real, em vez de apenas confirmar que a interface retorna 200.
- Descoberta: obtenha as versões realmente suportadas, o catálogo atual de ferramentas e os recursos integrados.
- Autorização: usuários comuns veem apenas as ontologias e sistemas de negócio permitidos; operações sem scope são recusadas.
- Estrutura de tabelas: nomes de exibição reais, colunas, tipos e permissões completos.
- SQL: consultas unidimensionais e multidimensionais, JOIN, datas, TopN e verificação de truncamento estão de acordo com os critérios reais de negócio.
- Conhecimento: localização, texto original completo e elegibilidade para citação como fato são consistentes entre si; perguntas mistas têm respaldo tanto em dados quanto em documentos.
- Search: verificações de modelo, init, sugestões, resultados, fechamento e integridade do buffer aprovadas.
- Análise e relatórios opcionais: estados reais de múltiplas ramificações, paginação, mudanças de permissão e cancelamento mantêm o comportamento original.
- Modelagem opcional: candidato, plano, aprovação original, aplicação efetiva e consulta de versão verificados fase a fase.
- Ações de negócio: verificação de hash de publicação, versão de destino, aprovação, idempotência e isolamento entre Grants.
- Recuperação: após um timeout de rede, o estado original é recuperado; após a atualização da fonte, a localização antiga deixa de valer e uma nova consulta é usada.
Registro de resultados
Registre a versão da instância, o papel do usuário, o escopo do Grant, a versão da configuração, as operações reais e os resultados. Marque separadamente o autoteste offline do cliente de protocolo, os valores esperados offline do exemplo CSV, a validação estática de Schema JSON e a verdadeira aceitação funcional online. Não extrapole a aprovação de uma fase para o produto inteiro.
Recursos de especificação e manutenção
Use o Schema completo de ferramentas incluído no manual e mantenha-o sincronizado com os resultados reais de descoberta da instância.
| Recursos | Conteúdo |
|---|---|
| reference/mcp-tool-catalog.json | 32 Schemas de entrada declarados no lado da ontologia e 8 no lado do negócio; algumas ferramentas incluem o Schema de saída original |
| reference/locales.json | 21 opções selecionáveis, 24 locales compatíveis e terminologia de UI |
| reference/search-keywords.json | Catálogo estático de palavras-chave com 17 locales explícitos |
| reference/analysis-contract-manifest.json | Restrições de versão de análise, ramificação, fatos, recibos e relatórios |
| examples/ | CSV sintético, descrição dos critérios, SQL de Top3, resultados esperados e cliente mínimo de protocolo |
Recursos de documentação integrados
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list e resources/read exigem que o usuário atual tenha ao menos uma das qualificações de leitura correspondentes: metadata, search operate ou etl operate. A documentação de ETL é uma referência estática entre produtos; a capacidade executável do Flash continua limitada ao escopo explicitamente relatado.
Referência externa de protocolo
Para o protocolo MCP e o contexto de autorização, consulte as especificações oficiais: https://modelcontextprotocol.io/specification/2026-07-28/basic e https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. Os endpoints, as ferramentas e o comportamento condicional deste produto seguem a implementação do r56 e os resultados atuais de descoberta da instância; não se deve equiparar o suporte geral ao protocolo à disponibilização de todos os recursos opcionais pelo servidor.
Manutenção e atualização
Ao atualizar, redescubra ferramentas e versões e compare os Schemas de entrada, os contratos de saída e as configurações; Grants antigos não recebem automaticamente novos scopes. Mantenha referências, caches e recibos vinculados à versão da fonte; após confirmar mudanças incompatíveis, obtenha novamente o contexto e não force o uso de localizações antigas em novos estados de negócio.
Referência de parâmetros de ferramentas: base e Search nativo
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfc_manual
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| names | array | Opcional ou condicionalmente obrigatório | Nomes explícitos a pesquisar, no máximo 32 por chamada. maxItems: 32 |
| action | string | Opcional ou condicionalmente obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: list, read, keywords, functions, etl_requests |
| locale | string | Opcional ou condicionalmente obrigatório | Locale explícito do catálogo estático de referência, não o idioma padrão da consulta. |
| uri | string | Opcional ou condicionalmente obrigatório | URI de recurso integrado listada pela ferramenta atual. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| data | object | Opcional ou condicionalmente obrigatório | Payload da ação original; consulte a descoberta de capacidades e a tabela de campos da ação. |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| data | object | Opcional ou condicionalmente obrigatório | Payload da ação original; consulte a descoberta de capacidades e a tabela de campos da ação. |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: capabilities |
dfc_ontologies
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| pageSize | integer | Opcional ou condicionalmente obrigatório | Registros por página; conforme o limite do Schema. minimum: 1; maximum: 100 |
| page | integer | Opcional ou condicionalmente obrigatório | Número da página, a partir de 1. minimum: 1 |
dfc_ontology_resources
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| resourceTypes | array | Opcional ou condicionalmente obrigatório | Conjunto de tipos de recursos a retornar. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| pageSize | integer | Opcional ou condicionalmente obrigatório | Registros por página; conforme o limite do Schema. minimum: 1; maximum: 100 |
| page | integer | Opcional ou condicionalmente obrigatório | Número da página, a partir de 1. minimum: 1 |
Referência de parâmetros de ferramentas: tabela, grafo e conhecimento
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfc_ontology_graph
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| relationTypes | array | Opcional ou condicionalmente obrigatório | Filtro por tipo de relação. |
| depth | integer | Opcional ou condicionalmente obrigatório | Profundidade de travessia dos vizinhos. minimum: 1; maximum: 3 |
| sourceTypes | array | Opcional ou condicionalmente obrigatório | Filtro por tipo de fonte. |
| query | object | Opcional ou condicionalmente obrigatório | Texto da consulta ou objeto de consulta versionado exato correspondente à action. |
| limit | integer | Opcional ou condicionalmente obrigatório | Limite de resultados retornados. minimum: 1; maximum: 100 |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| nodeKey | string | Opcional ou condicionalmente obrigatório | Chave de nó copiada do resultado real do grafo. |
| keyword | string | Opcional ou condicionalmente obrigatório | Palavras-chave de localização no grafo, não a sintaxe de consulta de dados por palavras-chave. |
| nodeTypes | array | Opcional ou condicionalmente obrigatório | Filtro por tipo de nó. |
dfc_ontology_query
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| routeLocators | array | Opcional ou condicionalmente obrigatório | Localizador de rota tipado emitido pelo servidor, copiado integralmente. maxItems: 20 |
| topK | integer | Opcional ou condicionalmente obrigatório | Limite de candidatos recuperados, sem garantia de cobertura completa. minimum: 1; maximum: 20 |
| queryMode | string | Opcional ou condicionalmente obrigatório | Modo de consulta de evidências, conforme o enum da ferramenta. enum: vector, hybrid, graph |
| fanoutPlan | object | Opcional ou condicionalmente obrigatório | Plano restrito de recuperação ramificada, conforme o Schema aninhado. |
| structuredPlan | object | Opcional ou condicionalmente obrigatório | Plano de vínculo contratual do servidor para a tabela completa do documento, não SQL. |
| knowledgeIds | array | Opcional ou condicionalmente obrigatório | ID da base de conhecimento no knowledgeBindings real. |
| query | string | Obrigatório | Texto da consulta ou objeto de consulta versionado exato correspondente à action. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
dfc_knowledge_search
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| topK | integer | Opcional ou condicionalmente obrigatório | Limite de candidatos recuperados, sem garantia de cobertura completa. minimum: 1; maximum: 20 |
| minScore | number | Opcional ou condicionalmente obrigatório | Pontuação mínima de correspondência. minimum: 0; maximum: 1 |
| knowledgeIds | array | Opcional ou condicionalmente obrigatório | ID da base de conhecimento no knowledgeBindings real. |
| query | string | Obrigatório | Texto da consulta ou objeto de consulta versionado exato correspondente à action. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| assetIds | array | Opcional ou condicionalmente obrigatório | IDs dos ativos de documento atualmente permitidos. |
| retrievalStrategy | string | Opcional ou condicionalmente obrigatório | Estratégia de recuperação efetivamente suportada. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| qdrantId | string / integer | Opcional ou condicionalmente obrigatório | Identificador de índice retornado pela localização real. |
| pageNo | integer | Opcional ou condicionalmente obrigatório | Página real ou número de página da paginação. |
| evidenceId | string | Opcional ou condicionalmente obrigatório | ID da evidência retornado pela mesma localização de conhecimento. |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: chunk, document, page_context |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| documentId | string / integer | Opcional ou condicionalmente obrigatório | ID do documento da mesma localização. |
| radius | integer | Opcional ou condicionalmente obrigatório | Faixa de páginas adjacentes. minimum: 0; maximum: 3 |
| chunkId | string | Opcional ou condicionalmente obrigatório | ID real do fragmento da mesma localização. |
dfc_table
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| maxRows | integer | Opcional ou condicionalmente obrigatório | Limite de linhas retornadas; não define o escopo de classificação no cliente. minimum: 1; maximum: 200 |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: detail, query |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| id | string | Opcional ou condicionalmente obrigatório | ID real do recurso de tabela, não o nome físico ou de exibição. |
| sql | string | Opcional ou condicionalmente obrigatório | Doris SQL somente leitura dentro do escopo de uma única ontologia, com colunas de saída explícitas. |
Referência de parâmetros de ferramentas: análise e relatórios
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfc_analysis_ask
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| question | string | Obrigatório | Pergunta em linguagem natural ou pergunta de acompanhamento compatível. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito da resposta ou da consulta; se omitido, aplicam-se as regras da ferramenta correspondente. |
| sessionId | string | Opcional ou condicionalmente obrigatório | Identificador real da sessão no mesmo Grant. |
dfc_analysis_refine
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| branchId | string | Opcional ou condicionalmente obrigatório | Identificador de ramificação estruturada emitido pelo servidor. |
| resultId | string | Obrigatório | Identificador do resultado de análise retornado originalmente. |
| question | string | Opcional ou condicionalmente obrigatório | Pergunta em linguagem natural ou pergunta de acompanhamento compatível. |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| change | object | Opcional ou condicionalmente obrigatório | Mudança em linguagem natural ou filter_patch tipado. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito da resposta ou da consulta; se omitido, aplicam-se as regras da ferramenta correspondente. |
| sessionId | string | Obrigatório | Identificador real da sessão no mesmo Grant. |
| expectedRevision | integer | Obrigatório | Pré-condição da versão original do resultado ou do cabeçalho de negócio; pode ser null na criação da pergunta. minimum: 1 |
| visualId | string | Opcional ou condicionalmente obrigatório | Identificador de visualização vinculado à ramificação. |
dfc_analysis_page
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| branchId | string | Obrigatório | Identificador de ramificação estruturada emitido pelo servidor. |
| resultId | string | Obrigatório | Identificador do resultado de análise retornado originalmente. |
| pageNo | integer | Obrigatório | Página real ou número da paginação. minimum: 1; maximum: 10000 |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| pageSize | integer | Obrigatório | Registros por página; conforme o limite do Schema. minimum: 1; maximum: 100 |
| sessionId | string | Obrigatório | Identificador real da sessão no mesmo Grant. |
| expectedRevision | integer | Obrigatório | Pré-condição da versão original do resultado ou do cabeçalho de negócio; pode ser null na criação da pergunta. minimum: 1 |
dfc_analysis_result_get
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| resultId | string | Obrigatório | Identificador do resultado de análise retornado originalmente. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| sessionId | string | Obrigatório | Identificador real da sessão no mesmo Grant. |
dfc_analysis_cancel
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| resultId | string | Obrigatório | Identificador do resultado de análise retornado originalmente. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| sessionId | string | Obrigatório | Identificador real da sessão no mesmo Grant. |
dfc_analysis_close
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| sessionId | string | Obrigatório | Identificador real da sessão no mesmo Grant. |
dfc_report_create
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| goal | string | Obrigatório | Objetivo da análise do relatório. |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito da resposta ou da consulta; se omitido, aplicam-se as regras da ferramenta correspondente. |
| title | string | Opcional ou condicionalmente obrigatório | Título opcional do relatório. |
dfc_report_status
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| reportId | string | Obrigatório | Identificador do relatório persistente do Grant atual. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
dfc_report_cancel
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| reportId | string | Obrigatório | Identificador do relatório persistente do Grant atual. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
Referência de parâmetros de ferramentas: modelagem e tarefa original
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfc_ontology_agent
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| mode | string | Opcional ou condicionalmente obrigatório | QUERY ou AUTHORING, com capacidades autorizadas separadamente. enum: QUERY, AUTHORING |
| instruction | string | Opcional ou condicionalmente obrigatório | Texto do requisito do usuário; mantenha o contexto consistente com o envio. maxLength: 16000 |
| idempotencyKey | string | Opcional ou condicionalmente obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. maxLength: 128 |
| action | string | Obrigatório | Nome da operação. Use conforme o enum atual e os parâmetros correspondentes à ação. enum: start, status, cancel |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| runId | string | Opcional ou condicionalmente obrigatório | ID da tarefa original da mesma ontologia e Grant. |
| contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
O objeto raiz de entrada desta ferramenta não tem campos; use um objeto arguments vazio.
dfc_artifact_context
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Opcional ou condicionalmente obrigatório | Tipo de escopo de recursos no contrato do artefato real. |
| ontologyId | string | Opcional ou condicionalmente obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| projectId | string | Opcional ou condicionalmente obrigatório | ID do projeto autorizado atualmente. |
| artifactId | string | Opcional ou condicionalmente obrigatório | ID real do artefato existente a editar. |
| instruction | string | Obrigatório | Texto do requisito do usuário; mantenha o contexto consistente com o envio. |
| variables | object | Opcional ou condicionalmente obrigatório | Objeto de variáveis fornecido conforme o contrato retornado. |
| previewInput | object | Opcional ou condicionalmente obrigatório | Entrada de pré-visualização limitada, fornecida conforme o contrato. |
| viewport | object | Opcional ou condicionalmente obrigatório | Viewport de exibição exigido pelo contrato original. |
dfc_ontology_table_schema
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| sourceAssetRef | string | Obrigatório | Referência estruturada de ativo já registrado, por exemplo table:123. |
| fields | array | Obrigatório | Campos da fonte atual e declarações opcionais de tipo explícito. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| proposalId | string | Obrigatório | ID do candidato original criado sob o Grant atual. |
| candidateHash | string | Obrigatório | Hash exato do candidato original do servidor. |
| previewInput | object | Obrigatório | Entrada de pré-visualização limitada, fornecida conforme o contrato. |
dfc_artifact_status
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| proposalId | string | Opcional ou condicionalmente obrigatório | ID do candidato original criado sob o Grant atual. |
| planId | string | Opcional ou condicionalmente obrigatório | ID do plano de aplicação imutável. |
dfc_artifact_plan
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| proposalId | string | Obrigatório | ID do candidato original criado sob o Grant atual. |
| candidateHash | string | Obrigatório | Hash exato do candidato original do servidor. |
| expectedTargetVersion | integer | Obrigatório | Pré-condição da versão de destino real atual. minimum: 0 |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
dfc_artifact_apply
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| planId | string | Obrigatório | ID do plano de aplicação imutável. |
| planHash | string | Obrigatório | Hash retornado pelo plano original. |
| approvalToken | string | Obrigatório | Material de aprovação emitido pelo servidor original; é proibido gerá-lo por conta própria. |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
dfc_artifact_submit
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| Configuração 1 / artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Configuração 1 / scopeType | string | Opcional ou condicionalmente obrigatório | Tipo de escopo de recursos no contrato do artefato real. |
| Configuração 1 / ontologyId | string | Opcional ou condicionalmente obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| Configuração 1 / projectId | string | Opcional ou condicionalmente obrigatório | ID do projeto autorizado atualmente. |
| Configuração 1 / artifactId | string | Opcional ou condicionalmente obrigatório | ID real do artefato existente a editar. |
| Configuração 1 / instruction | string | Obrigatório | Texto do requisito do usuário; mantenha o contexto consistente com o envio. |
| Configuração 1 / variables | object | Opcional ou condicionalmente obrigatório | Objeto de variáveis fornecido conforme o contrato retornado. |
| Configuração 1 / previewInput | object | Opcional ou condicionalmente obrigatório | Entrada de pré-visualização limitada, fornecida conforme o contrato. |
| Configuração 1 / viewport | object | Opcional ou condicionalmente obrigatório | Viewport de exibição exigido pelo contrato original. |
| Configuração 1 / contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. |
| Configuração 1 / contextHash | string | Obrigatório | Hash completo do contexto retornado por context. |
| Configuração 1 / baseArtifactHash | string | Obrigatório | Hash do artefato base retornado por context. |
| Configuração 1 / baseArtifactVersion | integer | Obrigatório | Versão base retornada por context. minimum: 0 |
| Configuração 1 / candidate | object | Obrigatório | Candidato que atende ao contrato retornado atualmente. |
| Configuração 1 / clientRequestId | string | Obrigatório | Chave de idempotência do cliente usada de forma estável pela solicitação de candidato atual. |
| Configuração 2 / artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: ONTOLOGY_RELEASE |
| Configuração 2 / contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. 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 |
| Configuração 2 / ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| Configuração 2 / candidateHash | string | Obrigatório | Hash exato do candidato original do servidor. |
| Configuração 2 / workspaceId | string | Obrigatório | Coordenadas reais do workspace do candidato. |
| Configuração 2 / workspaceRevision | string | Obrigatório | Versão exata do candidato; não usar latest. |
| Configuração 2 / releases | object | Obrigatório | Seleção de versões exatas fornecida conforme o contrato de publicação da ontologia. |
| Configuração 2 / selection | object | Obrigatório | Fornece apenas coordenadas explícitas de seleção de negócio; não fornece permissões nem prova de conclusão. |
| Configuração 2 / idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| Configuração 3 / Configuração 1 / artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: ONTOLOGY_RELEASE |
| Configuração 3 / Configuração 1 / contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. enum: ontology-workspace-create-mcp-submit-v1 |
| Configuração 3 / Configuração 1 / ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| Configuração 3 / Configuração 1 / workspaceId | string | Obrigatório | Coordenadas reais do workspace do candidato. |
| Configuração 3 / Configuração 1 / resources | array | Obrigatório | Declaração do modelo original compilada pelo servidor. minItems: 1 |
| Configuração 3 / Configuração 1 / idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| Configuração 3 / Configuração 2 / artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: ONTOLOGY_RELEASE |
| Configuração 3 / Configuração 2 / contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. enum: ontology-workspace-create-mcp-submit-v2 |
| Configuração 3 / Configuração 2 / ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| Configuração 3 / Configuração 2 / workspaceId | string | Obrigatório | Coordenadas reais do workspace do candidato. |
| Configuração 3 / Configuração 2 / resources | array | Obrigatório | Declaração do modelo original compilada pelo servidor. minItems: 1 |
| Configuração 3 / Configuração 2 / idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| Configuração 3 / Configuração 2 / releaseSelections | object | Obrigatório | releaseId exato de cada referência publicada e o fecho de dependências. |
| Configuração 4 / artifactType | string | Obrigatório | Tipo de artefato ou de publicação de ontologia efetivamente habilitado. enum: ONTOLOGY_RELEASE |
| Configuração 4 / contractVersion | string | Obrigatório | Deve ser usada a versão exata do contrato realmente suportada. enum: ontology-initial-activation-retirement-submit-v1 |
| Configuração 4 / ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| Configuração 4 / domainRid | string | Obrigatório | RID real do domínio de negócio. |
| Configuração 4 / consumerScopes | array | Obrigatório | Escopos exatos de consumidores permitidos pelo servidor. minItems: 1; maxItems: 256 |
| Configuração 4 / idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
Referência de parâmetros de ferramentas: entrada de conhecimento e escopo
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfc_ontology_knowledge_input_propose
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| request | object | Obrigatório | Solicitação de entrada de negócio original; conforme o Schema aninhado completo. |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. minLength: 1; maxLength: 128 |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade e o status da saída e os campos de autorização explicitamente definidos como false; não amplie por conta própria o significado de conclusão.
dfc_ontology_knowledge_input_preview
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. minLength: 1; maxLength: 128 |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade e o status da saída e os campos de autorização explicitamente definidos como false; não amplie por conta própria o significado de conclusão.
dfc_ontology_knowledge_question_submit
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| questionRevision | $ref | Obrigatório | Versão explícita da pergunta pendente de confirmação desta vez. |
| idempotencyKey | $ref | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. |
| originalInputKey | $ref | Obrigatório | Chave de idempotência correspondente à entrada de conhecimento original. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como string. |
| validUntil | $ref | Obrigatório | Fim da janela de validade da pergunta, em horário UTC. |
| expectedRevision | oneOf | Obrigatório | Pré-condição da versão original do resultado ou do cabeçalho de negócio; pode ser null ao criar a pergunta. |
| validFrom | $ref | Obrigatório | Início da janela de validade da pergunta, em horário UTC. |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade e o status da saída e os campos de autorização explicitamente definidos como false; não amplie por conta própria o significado de conclusão.
dfc_ontology_business_scope_initialize
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| domainRevisionId | string | Obrigatório | Versão exata do domínio de negócio. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Obrigatório | Chave de idempotência reutilizada de forma estável para a mesma operação lógica. minLength: 1; maxLength: 128 |
| businessSystemId | string | Obrigatório | ID real do sistema de negócio. minLength: 1 |
| ontologyId | string | Obrigatório | ID real da ontologia dentro desta autorização, preservado como string. minLength: 1 |
| domainRid | string | Obrigatório | RID real do domínio de negócio. minLength: 1; maxLength: 128 |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade e o status da saída e os campos de autorização explicitamente definidos como false; não amplie por conta própria o significado de conclusão.
Referência de parâmetros de ferramentas: espaço de trabalho de negócio
Nomes completos e campos de entrada, organizados para consulta por ferramenta.
As tabelas a seguir são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de pattern e alguns Schemas de saída constam em reference/mcp-tool-catalog.json; antes do envio final, ainda é necessário ler o tools/list do Grant atual. A indicação "opcional" na tabela não elimina os requisitos de validação interna das ações.
dfb_systems
O objeto raiz de entrada desta ferramenta não tem campos; use um objeto arguments vazio.
dfb_system_describe
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| systemId | string / integer | Obrigatório | IDs de sistema permitidos por este Grant de negócio. |
dfb_query
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| systemId | string / integer | Obrigatório | IDs de sistema permitidos por este Grant de negócio. |
| queryKey | string | Obrigatório | Chave de consulta publicada retornada por describe. |
| objectKey | string | Opcional ou condicionalmente obrigatório | Chave do objeto publicado. |
| pageSize | integer | Opcional ou condicionalmente obrigatório | Registros por página; conforme o limite do Schema. minimum: 1; maximum: 100 |
| page | integer | Opcional ou condicionalmente obrigatório | Número da página, a partir de 1. minimum: 1 |
| state | string | Opcional ou condicionalmente obrigatório | Filtro de status de negócio ou status do servidor. |
dfb_record
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| recordId | string / integer | Obrigatório | ID do registro de negócio atualmente permitido para leitura. |
| systemId | string / integer | Obrigatório | IDs de sistema permitidos por este Grant de negócio. |
dfb_work_items
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| systemId | string / integer | Obrigatório | IDs de sistema permitidos por este Grant de negócio. |
dfb_action_plan
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| expectedRecordVersion | integer | Opcional ou condicionalmente obrigatório | Versão atual de bloqueio otimista do registro de destino. minimum: 1 |
| systemId | string / integer | Obrigatório | IDs de sistema permitidos por este Grant de negócio. |
| commandType | string | Obrigatório | Tipo de comando no contrato publicado. |
| canonicalIrHash | string | Obrigatório | Hash atual do IR canônico publicado. |
| releaseId | string / integer | Obrigatório | ID real da versão do contrato publicado. |
| payload | object | Obrigatório | Payload em conformidade com o contrato de comando atual em describe. |
| releaseHash | string | Obrigatório | Hash real do contrato publicado. |
| targetRecordId | string / integer | Opcional ou condicionalmente obrigatório | Registro de destino real sobre o qual a operação será feita. |
| agentManifestHash | string | Obrigatório | Hash real do manifest de capacidades do Agent. |
| planIdempotencyKey | string | Obrigatório | Chave de idempotência estável do plano de negócio. |
dfb_action_status
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| actionPlanId | string / integer | Obrigatório | ID do plano de ação pertencente ao Grant de negócio atual. |
dfb_action_execute
| Parâmetro | Tipo | Requisito | Significado e escopo |
|---|---|---|---|
| approvalToken | string | Opcional ou condicionalmente obrigatório | Material de aprovação emitido pelo servidor original; é proibido gerá-lo por conta própria. |
| actionPlanId | string / integer | Obrigatório | ID do plano de ação pertencente ao Grant de negócio atual. |