Manual de integração de agentes e MCP do OT Flash
Protocolo, autorização, contratos de ferramentas e fluxo de chamadas completo
Utilize o Remote MCP público do OT Flash r56 para construir aplicações de dados e de conhecimento rastreáveis. Este manual apresenta o OAuth, as mensagens de protocolo, a referência de parâmetros de todas as ferramentas declaradas, as regras de evidência, as capacidades condicionais e os procedimentos de recuperação, e inclui um cliente executável e exemplos com dados sintéticos.
Programadores de agentes, engenheiros de integração e administradores
Os exemplos incluídos mantêm em chinês os nomes de apresentação dos campos. A tradução da interface e dos textos explicativos não altera os nomes reais de tabelas, colunas, valores de enumeração, nomes de ferramentas ou campos de protocolo.
Índice
- 1Âmbito de integração do agente e critérios de conclusão
- 2Ligação rápida e descoberta de capacidades
- 3Descoberta, registo e autorização OAuth
- 4Âmbitos, limites de recursos e permissões em tempo real
- 5Mensagens HTTP e do MCP moderno
- 6Compatibilidade com clientes do protocolo antigo
- 7Escolha a ferramenta e o canal de evidências corretos
- 8Recursos de ontologia e tipos de IDs
- 9Consultas a tabelas Doris e contrato de estrutura
- 10Top3 multidimensional e tratamento de truncamento
- 11Pesquisa de conhecimento: texto integral e elegibilidade de evidência
- 12Modelos e sessões nativos do Search
- 13Convenções de idioma e de região
- 14Análise combinada e resultados interativos
- 15Relatórios de visualização persistentes e MCP Apps
- 16Rascunhos de artefactos, pré-visualização, planos e aplicação
- 17Contrato de criação e publicação de candidatos de ontologia
- 18Modelos publicados, consulta de candidatos e fecho de referências
- 19Delegação de tarefas ao agente de ontologia
- 20MCP da área de trabalho de negócio
- 21Entradas de conhecimento de negócio e questões pendentes de confirmação
- 22Resposta, erros e repetição segura
- 23Segurança de integração e limites de capacidade
- 24Configuração pelo administrador e interruptores condicionais
- 25Cliente executável e exemplos de chamada
- 26Incorporar a interface de conversação da ontologia
- 27Lista de verificação de aceitação da integração
- 28Recursos normativos e manutenção
- 29Referência de parâmetros das ferramentas — base e Search nativo
- 30Referência de parâmetros das ferramentas — tabelas, grafo e conhecimento
- 31Referência de parâmetros das ferramentas — análise e relatórios
- 32Referência de parâmetros das ferramentas — modelação e tarefas originais
- 33Referência de parâmetros das ferramentas — entrada de conhecimento e âmbito
- 34Referência de parâmetros das ferramentas — área de trabalho de negócio
Âmbito de integração do agente e critérios de conclusão
Escolha o ponto de entrada de autorização e conclua consultas, recolha de evidências ou escritas controladas com base nos recibos do servidor.
O OT Flash r56 disponibiliza aos agentes externos capacidades de dados e de conhecimento no âmbito da ontologia através do Remote MCP, e fornece um ponto de entrada independente para a Área de trabalho de negócio. O agente deve decidir o trabalho executável com base no tools/list real, no inputSchema, no âmbito OAuth e nas permissões de recursos atuais; não pode inferir, a partir de um manual estático, que uma implantação já tem todas as funcionalidades opcionais ativadas.
| Ponto de entrada | Finalidade | Limites |
|---|---|---|
| /mcp | Ontologia, tabelas de dados, conhecimento documental, Search nativo e análise e modelação abertas condicionalmente | Interseção entre as permissões do utilizador atual e os recursos abrangidos por esta autorização |
| /mcp/business | Descoberta de sistemas de negócio, consultas, planos de ação, estados e execução | Autorização própria dos sistemas de negócio e contrato de publicação |
| Página de incorporação do agente de ontologia | Utilizar a conversa com a ontologia numa interface para utilizadores humanos | Depende de uma sessão real iniciada; não é um ponto de entrada para trocar Tokens MCP sem início de sessão |
Classificação de capacidades
- Leitura básica: ontologia e recursos, localização no grafo, pesquisa de conhecimento e texto integral, detalhes das tabelas autorizadas e Doris SQL.
- Delegação independente: o dfc_search exige search:operate e continua a utilizar as permissões do utilizador e do modelo originais.
- Abertura condicional: análise, relatórios persistentes, rascunhos de artefactos e respetiva aplicação, consultas ao modelo de ontologia e tarefas delegadas de agentes.
- Capacidades indisponíveis: o dfc_etl do Flash apenas comunica capabilities e não fornece execução de Heavy ETL. O AutoML e o ponto de entrada interno do espaço de trabalho FocusCode não fazem parte da API pública do Flash descrita neste manual.
Critérios de conclusão
As leituras de factos exigem um recibo real de consulta ou de texto integral; gerar candidatos exige indicar que ainda não foram aplicados; a publicação exige um recibo APPLIED real; o cancelamento deve distinguir pedido de confirmação. O texto da resposta, um HTTP 200, a indicação de que a ferramenta recebeu o pedido ou a descrição «concluído» do modelo não provam, isoladamente, o sucesso de uma operação de negócio.
O reference/mcp-tool-catalog.json complementar é a referência offline das declarações do r56: inclui as definições ativadas condicionalmente e não é o tools/list em tempo real de nenhum utilizador. O catálogo completo inclui 28 ferramentas centrais de ontologia, 4 extensões condicionais de controladores e 8 ferramentas do lado do negócio, o que não significa que todas estejam abertas por defeito.
Ligação rápida e descoberta de capacidades
Comece pelo domínio oficial da instância e descubra as ferramentas realmente disponíveis com o mínimo de privilégios.
- Obtenha do administrador o endereço raiz HTTPS oficial e a ontologia ou o sistema de negócio a aceder. Não utilize os domínios de exemplo da documentação para efetuar chamadas a sistemas de negócio reais.
- Configure o endereço do servidor MCP como https://flash.example.com/mcp; a área de trabalho de negócio utiliza /mcp/business no mesmo domínio.
- Desencadeie o início de sessão e a autorização OAuth, conforme o suporte do cliente, e confirme os recursos e o âmbito; não envie nome de utilizador e palavra-passe para o MCP.
- Utilize 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 um pedido pequeno e só de leitura, confirme os resultados estruturados e os erros e só depois execute o objetivo do utilizador.
Fragmento de configuração do cliente
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Este fragmento ilustra a intenção de configuração do endereço do servidor; a estrutura concreta do ficheiro de configuração e o suporte de OAuth dependem do cliente. Não escreva access_token, refresh_token, Cookie ou palavras-passe de administrador reais em ficheiros 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 dos recursos, o issuer do OAuth e o endereço externo do proxy inverso coincidem.
- O cliente suporta a geração de protocolo correspondente, em vez de enviar sempre initialize para o ponto de entrada do protocolo novo.
- A autorização atual está vinculada à ontologia ou ao sistema de negócio necessários.
- O Token é válido e os novos âmbitos opcionais já foram explicitamente autorizados.
Descoberta, registo e autorização OAuth
Utilize o código de autorização e o PKCE; não exponha ao agente as credenciais de início de sessão do produto.
| Endpoint | Método | Função |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Descoberta do recurso MCP da ontologia |
| /.well-known/oauth-protected-resource/mcp | GET | Descoberta compatível baseada no caminho do recurso da 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 | Registo dinâmico de public client |
| /oauth/authorize | Formulário GET ou POST | Início de sessão, seleção de recursos 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 | O utilizador com sessão iniciada consulta as ligações autorizadas |
| /oauth/grants/revoke | POST form | Revogar a ligação pelo fluxo da página original |
Sequência de autorização
- Leia os metadados dos recursos protegidos e do servidor de autorização. A resposta 401 a um pedido sem Token, juntamente com o cabeçalho WWW-Authenticate, indica o endereço de descoberta de recursos.
- Registe ou utilize uma identidade de cliente. O registo dinâmico de public client do r56 utiliza token_endpoint_auth_method=none; não substitua o PKCE por um segredo de cliente.
- Gere um state e um code_verifier aleatórios e calcule o code_challenge S256.
- Abra o endereço authorize indicado nos metadados, transmitindo response_type=code, client_id, redirect_uri exato, scope, resource, state, code_challenge e code_challenge_method=S256.
- O utilizador inicia sessão no DataFocus e escolhe a ontologia ou o sistema de negócio. O cliente não pode pré-selecionar recursos a que o utilizador não tem acesso.
- Receba a callback, valide o state e o issuer; troque o código de autorização usando o code_verifier original.
- Utilize o access_token apenas para autenticação Bearer no MCP. A renovação segue o fluxo original do OAuth; guarde de forma segura o refresh_token obtido na rotação.
Exemplo de registo
{
"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"]
}A callback de clientes Web usa HTTPS; clientes nativos podem usar endereços de loopback suportados. A autorização e a troca de Token exigem correspondência exata com a callback registada. Um Grant destina-se a um único protected resource; não misture âmbitos de ontologia e âmbitos da área de trabalho de negócio na mesma ligação.
Ciclo de vida dos Tokens
Por defeito, o servidor do r56 usa 3600 segundos para o access token, 2592000 segundos para o refresh token e 300 segundos para o código de autorização; a implantação pode substituir estes valores. O cliente deve basear-se no expires_in da resposta do token e nos erros reais, sem fixar os valores predefinidos. Atualize o Token após a renovação; revogar uma função, uma permissão de recurso ou um Grant faz com que as chamadas seguintes sejam rejeitadas.
Âmbitos, limites de recursos e permissões em tempo real
O âmbito autorizado delega as permissões existentes; não concede elevação de funções nem partilha estado de negócio entre Grants.
| Scope | Capacidades típicas | Restrições importantes |
|---|---|---|
| ontology.metadata:read | Ontologia, recursos e estrutura de tabelas | A ontologia e as tabelas têm de estar dentro da autorização e do âmbito atualmente legível |
| ontology.graph:read | Pesquisa no grafo e nós vizinhos | Devolve informação de localização, não evidência de factos |
| ontology.knowledge:read | Localização de conhecimento e texto integral | Preserva as permissões originais da base de conhecimento e dos documentos |
| ontology.table:query | SQL sobre tabelas da ontologia e consultas a modelos publicados | A consulta de tabelas exige também o âmbito metadata; as permissões reais da origem de dados e das colunas continuam a aplicar-se |
| search:operate | Modelos de palavras-chave nativos e sessões | Delegação independente e explícita; executada com as permissões originais do modelo e das colunas das tabelas do utilizador |
| etl:operate | Capabilities de Flash ETL | Não disponibiliza o Heavy ETL |
| authoring.contract:read | Contratos de modelação abertos condicionalmente | Exige ainda o interruptor de funcionalidade e os recursos correspondentes |
| authoring.artifact:read | Leitura de candidatos, planos, etc., no âmbito da autorização atual | Vinculada ao Grant e aos recursos do principal original |
| authoring.artifact:draft | Submissão de candidatos, pré-visualização, etc. | Não autoriza execução nem publicação |
| authoring.artifact:apply | Planos controlados e respetiva aplicação | Continuam a exigir a função de negócio, a política e a aprovação 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 condicionais de artefactos de fontes de dados HTTP | Cada item com interruptor independente e permissões originais |
Combinações de âmbitos exigidas para leitura
dfc_table detail exige ontology.metadata:read; query exige ainda ontology.table:query. dfc_ontology_query exige dois âmbitos de leitura, graph e knowledge. dfc_knowledge_search/detail exige knowledge. published_model/published_query utilizam table:query; candidate_query exige ainda authoring.artifact:read. As ferramentas de análise verificam também os âmbitos de evidência permitidos; os relatórios persistentes exigem metadata e table query.
Não codifique de forma fixa as autorizações predefinidas
O conjunto predefinido de âmbitos de ontologia do r56 inclui table query; Search e ETL são delegações explícitas. Prevalecem, em última análise, os metadados de descoberta, a página de autorização, o âmbito real do Token e o tools/list. As afirmações de documentação antiga, como «a ontologia nunca tem SQL por defeito» ou «existem apenas seis ferramentas», não servem de referência para a implementação atual.
Isolamento de estados
Sessões, relatórios, candidatos e planos de ação têm cada um o seu proprietário e âmbito. A renovação do access token não transfere o trabalho do Grant original para outro Grant. Não misture na ligação atual o sessionId, o reportId, o planId, os tokens de aprovação ou os Tokens de origem devolvidos por outra ligação.
Mensagens HTTP e do MCP moderno
Envie corretamente os metadados por pedido e os cabeçalhos de encaminhamento correspondentes, tratando separadamente o HTTP e os resultados das ferramentas.
| Aspeto | Comportamento do r56 |
|---|---|
| Transporte | Streamable HTTP sem estado, POST JSON-RPC |
| Identificadores suportados | 2026-07-28, bem como 2025-11-25, 2025-06-18 e 2025-03-26 |
| Métodos modernos | server/discover, tools/list, tools/call, resources/list, resources/read, abertos consoante as capacidades reais |
| Cabeçalho de sessão | Não é atribuído Mcp-Session-Id |
| GET e DELETE | /mcp e /mcp/business devolvem 405 |
| Notificações SSE do servidor | Não disponibilizadas nestes dois pontos de entrada públicos do MCP |
| Cache do catálogo | A descoberta moderna e a listagem devolvem ttlMs=60000 e cacheScope=private |
| Resultado normal | Os resultados modernos incluem resultType=complete e metadados de identidade de serviço |
Conteúdo que deve corresponder
- O MCP-Protocol-Version deve coincidir com io.modelcontextprotocol/protocolVersion em params._meta.
- O Mcp-Method deve coincidir com o método JSON-RPC.
- O Mcp-Name de tools/call deve coincidir com params.name; o cabeçalho de nome de resources/read deve coincidir com o URI.
- Cada pedido moderno transporta o 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": {}
}
}
}Para HTTP, os cabeçalhos correspondentes são Mcp-Method: tools/call e Mcp-Name: dfc_ontologies. Todos os ACCESS_TOKEN nos exemplos são marcadores de posição. Não coloque o Bearer Token no URL, nos parâmetros JSON nem em chaves de cache.
Leitura dos resultados
Processe primeiro o estado HTTP e depois verifique o erro JSON-RPC; quando houver um result, verifique também isError. Os resultados de ferramentas bem-sucedidos normalmente fornecem structuredContent, juntamente com conteúdo de texto contendo o mesmo JSON de negócio; leia primeiro o canal estruturado e evite agregar o text e o structuredContent em duplicado, como se fossem dois factos independentes. Um HTTP 200 pode transportar uma falha de ferramenta.
Recursos públicos e interface (UI)
O recurso de instruções incorporado não depende de MCP Apps. O ponto de entrada da área de trabalho de negócio não obtém, por isso, os recursos de instruções da ontologia. Os clientes que suportam visualização devem descobrir a respetiva UI através das capacidades reais e das _meta das ferramentas, sem adivinhar o URI de recursos não devolvidos.
Compatibilidade com clientes do protocolo antigo
Mantenha uma geração de protocolo consistente nos clientes que ainda utilizam 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 do protocolo e as capabilities negociadas pelo servidor.
- Envie as notificações de conclusão de inicialização necessárias de acordo com o protocolo do cliente; as notificações não têm resultados de ferramentas normais.
- Utilize tools/list para ler as ferramentas autorizadas atuais e depois envie tools/call.
- Mantenha os cabeçalhos e as mensagens consistentes com a geração de protocolo do pedido atual; não envie o fluxo antigo de initialize ou ping em mensagens 2026-07-28.
O protocolo antigo continua a utilizar o mesmo Bearer/OAuth, permissões e contratos de ferramentas. Não significa que o servidor forneça necessariamente ligações SSE persistentes de estilo antigo ou Mcp-Session-Id; os serviços públicos do r56 mantêm-se sem estado.
Erros de protocolo
| Situação | Resultado típico | Tratamento |
|---|---|---|
| Cabeçalhos e mensagens modernos inconsistentes | HTTP 400 JSON-RPC -32020 | Corrija os cabeçalhos, os metadados e os nomes das ferramentas |
| Versão não suportada | -32022 com a lista das versões suportadas | Selecione um protocolo efetivamente suportado |
| Método desconhecido | JSON-RPC -32601; os pedidos modernos podem devolver HTTP 404 | Verifique a geração do protocolo e o método |
| Parâmetros em falta ou inválidos | JSON-RPC: erro de parâmetros ou isError da ferramenta | Corrija de acordo com o inputSchema real |
Escolha a ferramenta e o canal de evidências corretos
Encaminhe com base na questão de negócio por resolver, em vez de repetir a recolha de evidências com 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 IDs de recursos e âmbito de visibilidade atual |
| Estatísticas de tabelas e TopN | dfc_table query | Recibo de execução bem-sucedida e evidenceRows completo |
| Consultar regulamentos, contratos ou relatórios | dfc_ontology_query ou knowledge search/detail | Texto original completo, autorizado e utilizável como facto |
| Localizar objetos no grafo | dfc_ontology_graph search/neighbors | Localizar a origem real e depois obter o facto correspondente |
| Interação nativa por palavras-chave | dfc_manual e depois dfc_search | Resultados reais no modelo e no frame de negócio originais |
| Análise combinada e relatórios | dfc_analysis_* ou dfc_report_* | Estado real de cada ramo estruturado e das evidências documentais |
| Alterar apresentação ou modelo de ontologia | dfc_authoring_* e ferramentas de artefactos | Verificar separadamente candidatos, planos, aprovações e a aplicação efetiva |
| Executar comandos de negócio | dfb_* de /mcp/business | Contratos publicados e recibo do ActionPlan original |
Evitar chamadas desnecessárias
Quando já possui uma estrutura de tabela atual, completa e autorizada, não solicite um novo detail em cada consulta; quando já possui uma localização fidedigna e evidências, não repita a mesma pesquisa. Quando faltar uma dimensão necessária, faça uma consulta suplementar limitada. Quando uma falha indicar claramente que não pode ser repetida, resolva primeiro a lacuna em vez de substituir a avaliação por «tentar outra vez».
Exclusões do Flash
As capabilities de dfc_etl podem devolver available=false e ETL_NOT_INCLUDED_IN_OT_FLASH. As descrições estáticas das funções ETL incorporadas servem como referência entre produtos, não provam que o Flash tem o ETL instalado nem permitem que o agente passe automaticamente a executar no Heavy ou noutro tenant.
Recursos de ontologia e tipos de IDs
Obtenha primeiro as coordenadas reais dos recursos para evitar confundir nomes de armazenamento, IDs de documentos e IDs de bases de conhecimento.
- Chame dfc_ontologies e navegue pelas ontologias abrangidas por esta autorização e ainda legíveis, usando page e pageSize.
- Use um ontologyId real para chamar dfc_ontology_resources; selecione tables, answers, pinboards, documents e knowledgeBindings conforme necessário.
- Trate a paginação de cada tipo de recurso em separado. pageSize tem um máximo de 100; não infira a totalidade dos recursos a partir da primeira página.
- Guarde os tipos declarados dos recursos e os IDs originais e use-os tal como estão nas chamadas seguintes.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordenadas | Fonte | Não pode ser substituído por |
|---|---|---|
| ontologyId | Lista de ontologias autorizadas ou contexto válido atual | ID de outra ontologia |
| id do recurso de tabela | Lista de tables ou contexto fidedigno | physicalName ou nome de apresentação da tabela |
| tblDisplayName colDisplayName | Metadados atuais de tabelas e colunas | Identificador SQL físico adivinhado |
| knowledgeId | knowledgeBindings ou recibo real de pesquisa de conhecimento | id do recurso de documento |
| assetId documentId chunkId evidenceId | O mesmo recibo real de localização | Campos concatenados a partir de resultados de localização diferentes |
| rid revisionId releaseId | Modelo publicado ou contexto de candidato do servidor | ID gerado localmente ou latest |
Convenções de precisão
Todos os identificadores de recursos de 64 bits devem preferencialmente usar cadeias decimais, sem conversão através de Number em JavaScript. Alguns esquemas de negócio aceitam string ou integer, o que não significa que a precisão inteira possa ser descartada. Locators opacos, UUID, hashes e tokens de utilização única também devem ser guardados tal como estão.
Consultas a tabelas Doris e contrato de estrutura
Execute SQL só de leitura em tabelas autorizadas, preservando a semântica de saída, os valores exatos e a integridade.
Leitura da estrutura
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}O detail usa IDs reais de recursos de tabela. Verifique schemaComplete, tblDisplayName, o colDisplayName em columns e o sqlDataType autoritativo, bem como o queryContract devolvido. dataType é apenas um mapeamento de compatibilidade; o nome de armazenamento físico não é o nome de tabela a utilizar no SQL submetido.
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
- Use os nomes de apresentação das tabelas e das colunas, com os identificadores entre aspas duplas. O pedido é uma consulta Doris só de leitura dentro do âmbito da ontologia.
- Liste explicitamente as saídas; SELECT * e table.* são proibidos; não podem ser usados para contornar as permissões de colunas registadas através de colunas físicas.
- As junções usam JOIN ... ON explícito; NATURAL JOIN e JOIN USING são rejeitados.
- Podem usar-se expressões só de leitura válidas, como agregações multidimensionais, CTE, janelas, CASE, COUNT(DISTINCT ...); o facto de a validação semântica não cobrir uma expressão não significa que a sua execução seja proibida de forma generalizada.
- Conclua primeiro agregações, ordenações e rankings em SQL e aplique depois o limite de resultados. maxRows é por predefinição 100, com um máximo de 200.
Datas e fusos horários
| Tipo ou objetivo | Forma | Nota |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) e CURRENT_DATE | Não se pode assumir o tipo de data diretamente a partir de literais de texto |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) e CURRENT_TIMESTAMP | Verifique o fuso horário da origem e o fuso horário da sessão |
| Tempo relativo | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Use as funções atuais correspondentes para datas e timestamps |
| Agrupamento temporal | YEAR(column) ou DATE_TRUNC(column, 'month') | Use um alias único para cada saída; queryContract é a referência |
O DATE('now', ...) do SQLite não é o contrato de datas do Doris para este ponto de entrada. Não coloque o método de verificação offline SQLite dos exemplos de documentação num SQL em produção.
Ler o recibo de consulta v8
O evidenceRows é o único canal do agente para dados de linha; os raw data não estão abertos ao agente. Os números de SQL são codificados como cadeias decimais exatas de JSON; avalie o seu valor numérico e tipo de negócio através de resultColumnContracts, sem o interpretar como VARCHAR só porque JSON é uma cadeia de caracteres. Leia executionReceipt, a informação de integridade e de truncamento, e preserve a informação de origem, como evidenceRowsSha256.
As saídas de consulta com recibo de execução citável podem ser citadas tal como estão; apenas a semântica validada no servidor autoriza cálculos determinísticos subsequentes. Não deduza «saldo acumulado», «valor no fim do período» ou «币种» a partir dos nomes dos campos, nem acrescente unidades por iniciativa própria. Resultados de zero linhas, falhas ou truncamentos não podem ser descritos como estatísticas completas.
Top3 multidimensional e tratamento de truncamento
Responda às classificações com agregações e funções de janela do servidor; não faça recálculos sobre resultados incompletos.
O ficheiro 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 montantes são iguais. Pedir maxRows=100 é suficiente para as 36 linhas do exemplo; para outros dados de negócio, avalie com base no número real de grupos.
- Obtenha a estrutura real e o critério atual, esclarecendo 币种, o período, 订单状态 e as regras de empate.
- Submeta SQL de agregação e classificação no servidor. Não consulte primeiro apenas os totais de 区域 e depois os trate como a classificação de 产品 por 类别.
- Verifique o contrato de colunas de saída e o evidenceRows real, confirmando que os dados devolvidos cobrem todos os grupos necessários.
- Ao detetar truncamento, faça consultas particionadas delimitadas pelos limites suportados pelo servidor, por exemplo obtendo o Top3 completo por 区域; mantenha sempre o mesmo critério de negócio.
- Se o período de origem mudar, consulte novamente e identifique claramente a nova versão; não misture versões de dados diferentes nem utilize cursores inválidos.
Recuperação de erros
TABLE_SCHEMA_INCOMPLETE exige a correção da estrutura ou a obtenção da estrutura completa; falhas como ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID são tratadas conforme o errorCode, retryable e remediation devolvidos. Não afirme que «todos os GROUP BY multidimensionais ou funções de janela estão proibidos», nem invente classificações sem resultados de consulta.
Pesquisa de conhecimento: texto integral e elegibilidade de evidência
Separe a localização, a leitura e a citação de factos, preservando a proveniência e a integridade.
Dois percursos comuns
| Percurso | Finalidade | Pontos-chave |
|---|---|---|
| dfc_ontology_query | Pesquisar no conhecimento vinculado à ontologia, podendo combinar com o encaminhamento pelo grafo | Verificar o canonical answerContextItems completo e a elegibilidade da evidência |
| dfc_knowledge_search → chunk de dfc_knowledge_detail | Localizar por pesquisa explícita e depois ler o fragmento escolhido | A pré-visualização da pesquisa não é facto; ler o texto integral 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 utilização como facto
- Verifique a ACL atual, a integridade do conteúdo e o canonicalFactEligible, citationEligible ou contrato de execução correspondente do servidor.
- Conteúdo completo vinculado a contentSha256. Truncamentos, omissões por orçamento ou conteúdo de baixa qualidade devem ser tratados conforme os campos reais.
- Metadados do documento, page_context, localização no grafo, resumos de pesquisa e pré-visualizações não substituem o texto canonical original.
- Copie preferencialmente evidenceId; quando forem necessários chunkId e documentId, devem provir da mesma localização, sem concatenações ou invenções.
Encaminhamento pelo grafo
Os resultados de search/neighbors são informação de localização. Passe à consulta (query) da ontologia apenas o objeto routeLocator devolvido completo pelo servidor, incluindo vínculo, versão e campos de prova. Não encapsule por iniciativa própria um assetId ou knowledgeId num locator como se tivesse sido emitido pelo servidor, nem devolva provas de origem afirmadas pelo modelo.
Recuperação de documentos estruturados
O structuredPlan de dfc_ontology_query é uma recuperação restrita com verificação determinística, dedicada a tabelas em documentos irregulares. Utilize o plano declarado pelo servidor apenas depois de terem sido devolvidos o executionContractSha256 atual, tableIndex, as colunas e a tabela completa. As tabelas de negócio já importadas devem seguir dfc_table SQL; não use a recuperação de tabelas Markdown como via para contornar a autorização de consulta de tabelas.
Estratégia de pesquisa
knowledgeIds normalmente é omitido para cobrir os vínculos atualmente ativos; se for indicado, use apenas IDs reais de base de conhecimento de knowledgeBindings. Não trate IDs de recursos de documentos como IDs de bases de conhecimento. Faça novas pesquisas delimitadas para questões por resolver, evitando repetições exatas sem evidência adicional.
Modelos e sessões nativos do Search
Use o protocolo de palavras-chave do Rust Search através de dfc_search e aguarde o estado terminal do frame de negócio original.
Ler as instruções 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 search:operate explícito. Encapsula o WebSocket de palavras-chave original, sem reescrever as palavras-chave como pedidos SQL ou LLM. A sessão fica vinculada ao tenant, utilizador, Grant, cliente e modelo atuais; as permissões das colunas das tabelas originais são verificadas novamente em 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 1 a 100 IDs reais de tabelas autorizadas, ou model_read lê um sourceToken que já possua.
- open devolve apenas initializationSent; faça primeiro poll, leia a resposta de negócio init original e confirme o sucesso.
- Leia o assist e as sugestões e depois envie uma message original suportada. Em query datas, isNl é fixado em false pelo wrapper.
- Leia frames continuamente, distinguindo sugestões, interpretação, receção e resultado final de negócio.
- No fim, faça close; para cancelar, use cancel e verifique a terminação conforme o estado real da tarefa.
| action | data | Significado |
|---|---|---|
| capabilities | Omitido ou objeto vazio | Ler ações, comandos, TTL e instruções de transporte |
| model_create | Matriz tableIds | Criar um modelo autorizado para o utilizador atual |
| model_read | sourceToken | Ler o modelo, filtrando colunas sem permissão e configurações de fontes sensíveis |
| open | sourceToken e language opcional | Estabelecer uma sessão nativa e enviar init |
| request | sessionId e message | Enviar uma mensagem original do protocolo type/datas |
| poll | sessionId e waitMillis entre 0 e 30000 | Retirar os frames atuais da memória intermédia com espera delimitada opcional |
| cancel close | sessionId | Fechar esta sessão nativa, sem poder afirmar um estado terminal de BI |
Comandos originais suportados
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteAs maiúsculas e minúsculas dos comandos e a estrutura de datas seguem as capabilities atuais e o protocolo da sessão original. Não adicione ao request ações inexistentes; por exemplo, a grafia de disambiguite deve ser mantida conforme o protocolo real. As mensagens têm um máximo de 256 Ki caracteres.
Sessões e integridade
O TTL da sessão é de 10 minutos e a sessão só é mantida enquanto o processo atual estiver ativo; não é uma tarefa recuperável de forma persistente. A memória intermédia guarda no máximo 256 frames e está sujeita a limites de memória; com bufferOverflow=true, os frames já retirados não podem ser tratados como resultado completo. Após um erro de transmissão, faça primeiro poll da sessão original; não reenvie às cegas consultas possivelmente já executadas.
O wrapper atual não fornece gravação de respostas ou pinboards, leitura e escrita do histórico, nem recuperação arbitrária de contexto. A existência de exportContext não significa que possa recuperar por iniciativa própria qualquer contexto. Para guardar resultados, use as capacidades de recursos originais realmente abertas na instância, sem inventar actions.
Convenções de idioma e de região
Preserve as fronteiras entre o locale da interface, o dicionário de consulta, o idioma da resposta e os nomes originais dos campos.
A prioridade é: idioma explicitamente pedido, idioma do sistema de aplicação, locale do nó de execução real. Valores omitidos, null, cadeias vazias e espaços em branco não recorrem por defeito ao chinês. Os valores de região em languageRegistry devem permanecer exatos; não reduza arbitrariamente en-GB, fr-CA, pt-BR, es-US ou ar-AE a 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 e o catálogo do chinês tradicional são distintos |
| Inglês dos EUA, Reino Unido, Austrália e Canadá | en-US en-GB en-AU en-CA | Os pacotes de interface/palavras-chave podem ser partilhados; os metadados de região são preservados |
| Alemão, italiano, russo | de-DE it-IT ru-RU | Conforme as sugestões da sessão atual |
| Espanhol de Espanha e da América Latina | es-ES es-US | O ID de região do produto é es-US |
| Francês de França e do Canadá | fr-FR fr-CA | IDs de região não são fundidos |
| Português de Portugal e do Brasil | pt-PT pt-BR | Catálogo e convenções regionais são mantidos em separado |
| Neerlandê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 divida palavras segundo as regras de espaços 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 só tem os locales explicitamente listados; quando é omitido, usa a referência em inglês; este é um valor predefinido de referência, não uma regra de análise do idioma de consulta. Quando uma variante regional não tiver catálogo estático, obtenha as sugestões reais através do assist da sessão atual, sem fabricar alias nem resultados de retrocesso. O names admite no máximo 32 itens por chamada.
O que não traduzir
- Tabelas, colunas, valores de enumeração, nomes de clientes, nomes de fórmulas e outras cadeias reais do modelo.
- Nomes de ferramentas, actions, scopes, campos de Schema, códigos de erro e valores de estado.
- IDs de recursos, hashes, locators opacos e referências emitidas pelo servidor.
Por exemplo, uma pergunta em alemão pode consultar uma coluna apresentada em chinês, como «销售金额». Mudá-la para um nome de coluna em alemão cria outro identificador, não uma tradução de interface. Após mudar de 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 combinada e resultados interativos
Nas ferramentas de análise disponibilizadas condicionalmente, preserve a autorização, a versão, o ramo e o estado da evidência.
dfc_analysis_* é controlado por datafocus.mcp.analysis.tools.enabled. A parte estruturada continua a passar pela consulta autoritativa do Search e pela política de linhas atual; a parte documental volta a obter o texto integral sob a ACL atual. 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 | Colocar uma pergunta de análise em linguagem natural | question e ontologyId; opcionais: language e sessionId |
| dfc_analysis_result_get | Ler um resultado já devolvido | ontologyId sessionId resultId |
| dfc_analysis_refine | Aprofundar ou alterar com base no resultado completo mais recente | expectedRevision do resultado original e chave de idempotência estável |
| dfc_analysis_page | Obter uma página de um ramo do servidor | Ramo original, versão do resultado, pageNo pageSize |
| dfc_analysis_cancel | Cancelar um resultado ainda em execução | Sessão e resultado originais |
| dfc_analysis_close | Libertar uma sessão sem trabalho em curso | Sessão original |
Iniciar a análise
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Leia o sessionId, resultId, estado e revision devolvidos; se necessário, continue a ler o resultado original.
- Verifique individualmente o estado, a integridade, a política de linhas e a proveniência de cada ramo estruturado; um ramo completo não significa que toda a análise esteja completa.
- Verifique a evidência documental, o registo de factos, a elegibilidade de citação e as limitações. As narrativas geradas pelo modelo não podem, por si só, elevar a elegibilidade da evidência.
- Se precisar de aprofundar, baseie-se no resultado completo mais recente e indique expectedRevision; repetições da mesma alteração reutilizam a mesma chave de idempotência.
- Antes de fechar, confirme que a sessão já não está em execução; cancelar e fechar são ações distintas.
Filtragem controlada e paginação
O filter_patch utiliza branchId, fieldRef, valueRef e os operadores permitidos indicados pelo servidor; a filtragem tipificada atual declara apenas EQ. É proibido substituir as referências opacas por SQL em bruto, tableId, columnId ou por uma árvore de filtros fabricada no cliente. Na paginação, pageNo começa em 1, com o máximo de 10000; pageSize tem o máximo de 100.
Sugestões de capacidades e comportamento
As annotations das ferramentas são sugestões para o cliente, não autorizações de segurança. Alguns templates genéricos utilizam readOnlyHint, o que não substitui a avaliação da ação real; cancelar, fechar e criar relatórios alteram o respetivo estado de trabalho. Execute sempre de acordo com a semântica da ferramenta, o objetivo do utilizador e as permissões do servidor.
Relatórios de visualização persistentes e MCP Apps
Crie relatórios recuperáveis e leia os respetivos resultados e interfaces interativas de acordo com as permissões atuais.
dfc_report_* é controlado por datafocus.mcp.analysis.report-tools.enabled e exige os âmbitos metadata e table query. Ao contrário das sessões Search mantidas no processo, os relatórios utilizam um reportId persistente; 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, utilize um idempotencyKey estável, com 8 a 128 caracteres suportados.
- Guarde o reportId, consulte periodicamente o status e verifique o estado real: concluído, com falha, parcialmente concluído ou cancelado.
- Ao ler os resultados, confirme os ramos estruturados, as visualizações, as fontes dos factos, as referências documentais e a integridade.
- Para cancelar um relatório não concluído, utilize o reportId original; não crie outro relatório em substituição do cancelamento.
- Após um timeout de rede, leia primeiro o estado do relatório original; a repetição com a mesma chave de idempotência deve manter a mesma intenção de negócio.
MCP Apps
Os clientes que suportem extensões de UI leem as páginas dos relatórios através do _meta das ferramentas e da descoberta real de recursos. A página do relatório persistente correspondente ao r56 é ui://datafocus/analysis-report/v16/index.html; a análise interativa utiliza as referências correspondentes de recursos do servidor; os clientes não devem codificar de forma fixa valores que substituam os retornos das ferramentas. Sem extensão de UI, os resultados estruturados continuam a poder ser lidos.
Vinculação de fontes
A leitura do relatório volta a verificar o Grant, o vínculo à ontologia e à origem do pedido e as permissões atuais de tabela. A integração cross-origin no navegador deve utilizar origens reais aprovadas; o cliente não contorna o vínculo falsificando o Origin. Um reportId antigo não é uma ligação pública de longa duração nem uma credencial de acesso entre utilizadores.
Rascunhos de artefactos, pré-visualização, planos e aplicação
Entregue o conteúdo gerado ao servidor original para normalização, validação e aprovação, sem permitir que o modelo altere diretamente os recursos de produção.
As ferramentas de artefactos exigem a funcionalidade authoring ativada, um artifact type real, o âmbito relevante e permissões de escrita do administrador original. Os tipos predefinidos são CONTROL_PANEL_SPEC e VIEW_SPEC; outros formulários, origens HTTP ou tipos de script estão ainda sujeitos a configuração independente. O Flash não tem AutoML, pelo que os tipos relacionados não são apresentados como artefactos 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.
- No cliente, gerar candidatos com base no contrato real, sem executar o respetivo código.
- dfc_artifact_submit submete o contexto original e os candidatos, mantendo a instruction idêntica e utilizando um clientRequestId estável.
- Ler proposalId, candidateHash, os resultados da validação e a pré-visualização; havendo erros reais, corrigir os candidatos, sem forjar um estado de validação bem-sucedida do servidor.
- Quando for necessária nova pré-visualização, utilizar dfc_artifact_preview e o mesmo hash de candidato.
- dfc_artifact_plan cria um plano imutável, utilizando o candidato real, a versão de destino e a chave de idempotência.
- Tratar a aprovação conforme a interação original ou a política já autorizada e, em seguida, chamar dfc_artifact_apply; apenas o recibo APPLIED representa a aplicação efetiva.
Pedido de contexto mínimo
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC utiliza o projectId atualmente autorizado; ao editar um artefacto existente, utiliza o artifactId real. Campos como variables, previewInput e viewport são fornecidos conforme o contrato devolvido, sem inventar a estrutura interna dos candidatos.
Concorrência e repetições
O plano está vinculado à versão de destino, ao hash do candidato e à chave de idempotência. Após alteração do destino, o plano antigo não pode continuar a ser aplicado; voltar a ler o contexto e tratar o conflito real. Um timeout de transporte não prova falha; consultar primeiro com dfc_artifact_status o proposalId ou planId original. READY não é APPLIED.
Aprovação e política automática
Os planos genéricos de artefactos exigem a aprovação humana original. Os planos conformes à política de publicação automática da ontologia são tratados segundo approvalMode, sem exigir que o utilizador assine adicionalmente uma aprovação inventada pelo agente. approvalToken é material emitido pelo servidor e não pode ser substituído por uma cadeia escrita pelo agente; o inputSchema real e o recibo do plano determinam os campos obrigatórios.
Contrato de criação e publicação de candidatos de ontologia
Utilize declarações de ontologia e uma configuração de publicação com versões independentes, sem aplicar à publicação de modelos o contrato dos artefactos de apresentação comuns.
Criação de candidatos
O contentor da ontologia já deve existir e estar dentro do Grant. Utilizar dfc_ontology_table_schema para verificar os campos atuais das origens estruturadas e a impressão digital do Binding v4; os campos podem fornecer apenas sourceField para descoberta automática do tipo. As declarações explícitas DECIMAL exigem a precisão e as casas decimais atuais; outros tipos não transportam estes 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
| Contrato | Finalidade | Limites essenciais |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Criar candidatos a partir de declarações locais | Origens realmente autorizadas, compilação no servidor; não são aceites provas de conclusão |
| ontology-workspace-create-mcp-submit-v2 | Combinar referências locais com referências publicadas exatas | Fornecer releaseSelections exatos e as dependências do fecho |
| ontology-publication-mcp-submit-v1 até à v3 | Vincular um candidato existente ao pedido de plano de publicação | Coordenadas explícitas; o destino, a origem, a aprovação e a validação são recuperados pelo servidor |
| ontology-publication-mcp-submit-v4 até à v6 | Configuração associada de publicação automática ativada de forma independente | Utilizar apenas quando as capabilities e o schema real o declararem |
| ontology-initial-activation-retirement-submit-v1 | Operação controlada de ativação inicial e retirada | Plano independente, nova aprovação humana e âmbito exato |
Sequência de publicação
- Obter, para o candidato atual, workspaceId, workspaceRevision, candidateHash e as origens reais.
- Escolher a versão do contrato conforme as capacidades do servidor; submeter coordenadas como releases e selection, sem incluir campos que se declarem «aprovado» ou «validado».
- Conservar o proposalId devolvido pelo submit e o idempotencyKey original. O submit e o MODEL_PLAN são fases diferentes do mesmo pedido.
- Chamar dfc_artifact_plan, utilizando o candidato original, a versão de destino e a mesma chave de idempotência.
- PLANNING_INCOMPLETE significa apenas que ainda não se formou um plano válido; VALIDATION_UNSATISFIED indica que a validação atual ainda tem lacunas, a tratar conforme nextAction.
- Após o êxito do plano, continuar com base em HUMAN_REQUIRED ou POLICY_AUTO, utilizando os mecanismos originais de aprovação e de publicação.
- Confirmar o resultado com o recibo APPLIED e, em seguida, com a leitura real do modelo publicado e com consultas autorizadas.
Tempos limite e recuperação
Após timeout de PLAN, ler o proposalId original. MODEL_PLAN_SUBMITTED é um pedido não concluído; MODEL_PLAN_COMPLETED significa que se deve recuperar o recibo original com as mesmas coordenadas e a mesma chave, e não criar um novo pedido no cliente. Lacunas de validação em estado terminal não podem ser convertidas em aprovação de publicação trocando a chave ou submetendo novamente.
Permissões humanas de negócio
A instruction e as declarações fornecidas pelo agente são entradas do agente, não assinaturas de políticas por pessoas. 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 a ACL da origem continuam a ser decididos pelos mecanismos originais. Não substituir estes factos por campos do cliente.
Modelos publicados, consulta de candidatos e fecho de referências
Utilize o conhecimento de negócio publicado em versões exatas e preserve o carácter temporário dos candidatos não publicados.
O published_model, o published_query e o candidate_query de dfc_ontology_graph são configurações estruturadas de abertura condicional, e não sinónimos das operações search/neighbors comuns. São autorizados por table query e pelas permissões de leitura de modelação necessárias; a visibilidade no grafo não substitui as permissões de tabela.
Leitura do modelo publicado
- Quando a enumeração de action da ferramenta inclui efetivamente published_model, submeter um releaseId committed real.
- A v1 devolve 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 vinculação compactos.
- Escolher objetos, propriedades, Bindings, âmbitos e versões a partir dos valores realmente devolvidos, sem gerar RIDs nem utilizar latest.
- Submeter consultas tipificadas fixas do published_query; os resultados continuam sujeitos à autorização atual da origem e dos campos.
Consulta de candidatos
O candidate_query utiliza workspaceId real, revision, candidateHash e as declarações do candidato. Ao combinar com referências publicadas, utilizar as coordenadas tipificadas v2 correspondentes LOCAL/PERSISTED e uma seleção exata. Os resultados de candidatos são sempre não publicados e temporários e não devem ser tratados como conhecimento confirmado pela empresa.
Manutenção parcial e fecho
Selecionar apenas as dependências transitivas exigidas pela raiz do candidato e garantir que cada referência publicada tem um releaseSelections exato. Copiar o corpo da publicação, submeter apenas um conjunto de IDs ou alargar a todos os recursos históricos não substitui a verificação atual das dependências e origens.
A query destas actions é um objeto tipificado e versionado, não aceitando SQL, IDs de tabelas físicas ou nomes de tabelas de origem em substituição das suas referências de negócio. Os templates de metadados e os resultados do grafo não são, por si só, elegíveis como referência de factos.
Delegação de tarefas ao agente de ontologia
Retome o trabalho com tarefas persistentes e o Grant original, sem tratar as instruções do agente como aprovação humana.
dfc_ontology_agent só é apresentado quando o Pi Runtime real e as permissões relevantes estão disponíveis. QUERY utiliza a capacidade de leitura; AUTHORING exige ainda a função de modelação e o âmbito authoring correspondente. Não disponibiliza outro motor 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 de parâmetros estrito
O start utiliza contractVersion, action, ontologyId, mode, instruction, idempotencyKey; o status/cancel utiliza contractVersion, action, ontologyId, runId. O servidor verifica o conjunto exato de campos conforme a action. A instruction tem no máximo 16000 caracteres; a chave tem de 1 a 128 caracteres suportados e começa por letra ou dígito.
Retoma e cancelamento
- Conservar o runId original, o Grant, o mode e a chave de idempotência.
- A mesma chave com a mesma instruction retoma o mesmo run, sem voltar a submeter outra tarefa; a mesma chave com instrução diferente é recusada.
- O status consulta o estado da tarefa original. Mesmo após a conclusão, é preciso verificar as suas consultas de tabela, evidências ou recibos de publicação.
- O cancelamento utiliza o runId original; confirmar o resultado com o estado real da tarefa.
A conclusão do run não é um recibo de publicação de modelo. A tarefa de publicação continua a ser confirmada pelo estado original do artefacto e pelas verificações de origem; QUERY não confere direitos implícitos de escrita ou publicação.
MCP da área de trabalho de negócio
Consulte registos com base em contratos de negócio publicados e execute comandos através do ActionPlan original.
O /mcp/business utiliza um protected resource independente e a seleção do sistema de negócio, não podendo reutilizar o Grant da ontologia em substituição da autorização de negócio. O sistema de negócio tem de estar publicado, estar disponível para invocação pelo agente e cumprir a política de segurança original, e o utilizador atual tem de ter as funções e capacidades de runtime reais.
| Scope | Ferramenta | Limites |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Descobrir apenas os sistemas abrangidos por esta autorização e atualmente invocáveis |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Registos legíveis pelo utilizador atual e os seus próprios planos |
| business-system:plan | dfb_action_plan | Apenas cria planos imutáveis, sem os executar |
| business-system:execute | dfb_action_execute | Autorização independente e explícita, execução segundo o risco e a 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 utiliza queryKey publicado, especificando conforme necessário objectKey, state, page e pageSize. Não executa SQL arbitrário.
- dfb_record e dfb_work_items leem os registos e tarefas pendentes atualmente permitidos.
- Antes da execução, utilize dfb_action_plan para fornecer o releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey reais e o payload do contrato.
- Verificar riskClass, requiresApproval e status; quando envolver registos de destino, conservar expectedRecordVersion.
- dfb_action_execute executa apenas planos detidos pela ligação atual e já prontos; os tokens de aprovação exigidos para a aprovação humana são emitidos pelo DataFocus.
- Após falha ou timeout, dfb_action_status recupera o plano original; a repetição mantém a semântica de idempotência original.
Ligação e vinculação de versões
Os planos estão vinculados ao ID estável de isolamento do Grant atual. Após a renovação do Access Token, os planos da mesma ligação continuam a poder ser processados; outra ligação OAuth não os pode assumir. Na execução são reavaliadas a versão publicada, os hashes de IR/manifest, a versão dos registos de destino, a expiração do plano, a idempotência e a aprovação. A allowlist OAuth não permite contornar a governação de negócio.
Entradas de conhecimento de negócio e questões pendentes de confirmação
Registe entradas de negócio quando o processador de produção correspondente estiver ativo e preserve o limite de confirmação humana.
As quatro ferramentas seguintes são adicionadas condicionalmente pelo controlador MCP público, conforme os processadores instalados e o âmbito atual. Não aparecem sempre no catálogo base. A existência de um Schema declarado não significa que a instância tenha processadores, orçamento ou permissões completos; é obrigatório verificar primeiro tools/list.
| Ferramenta | Finalidade | Autorizações ou efeitos que não produz |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registar a entrada de negócio original num espaço de trabalho existente | Não gera questões de confirmação, não aprova, não publica |
| dfc_ontology_knowledge_input_preview | Pré-visualização temporária de rascunhos de questões a partir da entrada original | Não persiste, não confirma, não produz recibos de produção |
| dfc_ontology_knowledge_question_submit | Guarda questões authored e ainda não confirmadas | Não combina respostas automaticamente nem obtém permissões de responsável ou direitos de publicação |
| dfc_ontology_business_scope_initialize | Inicialização explícita de um âmbito de consumidor de sistema de negócio | Não publica, não ativa, não concede acesso à origem |
Entrada e pré-visualização
- Obter workspaceId, workspaceRevision, localRef e preparationDigest a partir do trabalho de preparação real.
- propose regista 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; devolve em cada chamada a revision do servidor e uma janela de 60 segundos, não sendo um recibo de conclusão idempotente da produção.
- Quando for necessário armazenar uma questão, o question_submit usa uma nova chave de comando, a originalInputKey original, questionRevision, validFrom, validUntil e expectedRevision explícitos; na criação, expectedRevision é null.
Ponto de entrada de confirmação humana
A knowledgeConfirmationPage devolvida pelo question_submit é apenas uma localização relativa na página original com sessão iniciada, com uma questão pré-preenchida. Não inclui Bearer, não abre a página automaticamente e não confirma conhecimento. QUESTION_STORED_UNCONFIRMED indica claramente que o conhecimento ainda não foi confirmado e não pode ser apresentado nas respostas como «o conhecimento foi publicado».
Inicialização do âmbito do consumidor
O business scope initialize exige simultaneamente a permissão de publicação da ontologia e a permissão de criador ou de gestão SourceManager do sistema de negócio exato. Utiliza as coordenadas reais de domainRid, domainRevisionId e businessSystemId; o cliente não pode preencher um consumerScope arbitrário nem uma prova de conclusão. A INITIALIZED e a COMPLETED devolvidas continuam a indicar claramente published=false e activationAuthorized=false.
Estes pedidos estão igualmente sujeitos a validações rigorosas de JSON, do conjunto de campos, dos bytes e da profundidade. O limite de entrada dos pedidos é 1 MiB; algumas operações concretas têm limites inferiores. Os Schemas completos de entrada e de saída são fornecidos com a referência da ferramenta; a lógica flexível de parâmetros de um wrapper MCP genérico não pode ser aplicada a estes contratos rigorosos.
Resposta, erros e repetição segura
Explique os erros por camadas, mantendo as coordenadas da tarefa e a semântica de idempotência.
| Camada | Conteúdo verificado | Princípio de tratamento |
|---|---|---|
| Rede e HTTP | Ligação TLS, 401, 403, 400, 404, 405, etc. | Não tratar uma resposta de falha como um resultado de consulta normal |
| JSON-RPC | error.code, message, data | Distinguir problemas de protocolo, método, parâmetros e autorização |
| Ferramenta MCP | result.isError e structuredContent | Um HTTP 200 ainda pode significar falha |
| Resultado de negócio | Estado real, integridade, motivo da falha, nextAction | Recebido ou pronto não equivale a concluído |
| Elegibilidade factual | executionReceipt, citationEligible, contentComplete | Conteúdo sem elegibilidade serve apenas para localizar ou explicar lacunas |
Situações comuns de HTTP
- 401: Bearer em falta ou inválido; renovar ou voltar a autorizar segundo o fluxo OAuth atual.
- 403: Grant, função, recurso selecionado, permissões de origem, Origin ou configuração não satisfeitos; não contornar com repetições.
- 400: mensagem ou contrato versionado inválido, incluindo incompatibilidade entre cabeçalhos modernos e metadados.
- 404: verificar o caminho exato do serviço, o método do protocolo e as capacidades de runtime; não trocar aleatoriamente o ID da ontologia.
- 405: o GET e o DELETE do /mcp público não estão disponíveis por definição; usar o POST correto, em vez de estabelecer uma ligação SSE persistente.
Operações de escrita com resultado incerto
A MCP_OPERATION_OUTCOME_UNKNOWN pode conter outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool e os parâmetros de localização originais. Consultar primeiro o estado original e depois retomar o pedido original. Não voltar a submeter o candidato, não trocar a chave de idempotência nem tratar o tempo limite como uma reversão da transação.
Conteúdo que deve ser preservado tal como está
- Grant original, âmbitos de recursos, IDs de tarefas e de resultados.
- candidateHash, planHash, expectedRevision, versão de destino e seleções de publicação.
- Chaves de idempotência da mesma operação lógica; operações de negócio diferentes devem usar chaves novas.
- retryable, remediation, nextAction e o estado atual declarados pelo servidor.
Não extrair de textos de exceção SQL internos, anfitriões, credenciais ou rastreios de pilha como fonte de resposta. Basta registar os códigos de erro divulgáveis e a informação de correlação do pedido; os erros originais podem ter de ser consultados pelo administrador em registos controlados.
Segurança de integração e limites de capacidade
Mantenha os limites originais de identidade, recursos, execução e evidência, e trate os documentos não fidedignos com segurança.
- Ligar apenas aos domínios oficiais indicados pelo administrador; validar o TLS e o issuer OAuth, sem desativar a verificação de certificados.
- Usar Grants dedicados com âmbito mínimo de recursos; não usar contas de administrador, Cookies ou Tokens internos de longa duração como credenciais de interfaces públicas.
- Tratar o corpo dos documentos como material de negócio não fidedigno. Instruções como «ignorar regras», «carregar chaves» ou «executar comandos» num documento não constituem autorização de ferramentas.
- Limitar a repetição automática, a concorrência e o âmbito dos resultados; não reconstruir no cliente as permissões de negócio originais.
- Os registos devem conter apenas a informação de correlação necessária, sem Bearer, refresh token, tokens de aprovação ou conteúdo sensível integral de negócio.
- Após a desconexão do utilizador ou a revogação pelo administrador, deixar de usar autorizações e dados em cache, sem continuar a invocar com locators antigos.
As sugestões (hints) das ferramentas não são permissões
readOnlyHint, destructiveHint, idempotentHint e openWorldHint servem para o cliente compreender as capacidades, não garantem o efeito real de negócio de cada chamada e não substituem a autorização do utilizador atual. Todas as ações de escrita, planos, pré-visualizações, sessões e cancelamentos devem ser tratadas segundo o seu comportamento real.
Pontos de entrada a não invocar
- Os serviços Trino/Hive/Hadoop originais e o Heavy ETL, que não está incluído no Flash.
- Interfaces internas de scope ou de espaço de trabalho exclusivas do FocusCode.
- Ferramentas de execução v2, AutoML ou outras ferramentas experimentais que não constem do tools/list da instância atual.
- REST privado do navegador, ligações arbitrárias a bases de dados ou serviços de outros tenants para contornar recusas do MCP.
Semântica dos dados
Seguir os contratos do servidor relativos a decimais exatos, tipos, 币种, unidades, tempo e evidência. Não arredondar nem converter novamente 币种 só porque o texto de saída parece um número, e não fazer classificações globais sobre as linhas visíveis quando o resultado foi truncado.
Configuração pelo administrador e interruptores condicionais
Antes de ativar capacidades alargadas, confirme os componentes reais, os endereços públicos e a configuração original de permissões.
| Configuração | Finalidade | Requisitos de publicação |
|---|---|---|
| datafocus.mcp.public-base-url | Endereço raiz externo oficial | Descoberta OAuth, issuer, callback e proxy inverso consistentes |
| datafocus.mcp.allowed-origins | Origens adicionais do navegador aprovadas | Configuração exata, sem alargar a origens arbitrárias |
| datafocus.mcp.oauth.route-proof-secret | Segredo de servidor dedicado para prova de encaminhamento do grafo | Guardar separadamente, sem usar o Bearer como segredo |
| datafocus.mcp.analysis.tools.enabled | Ferramentas de análise interativa | Serviços de dados, conhecimento e permissões associados realmente disponíveis |
| datafocus.mcp.analysis.report-tools.enabled | Ferramentas de relatórios persistentes | Armazenamento associado, worker e cadeia de recuperação disponíveis |
| datafocus.mcp.analysis.apps.enabled | Apresentação com MCP Apps | O cliente declara suporte e verifica o _meta devolvido |
| datafocus.mcp.authoring.enabled | Contratos de rascunho e modelação | Preservar permissões originais de administrador e de recursos |
| datafocus.mcp.authoring.apply-enabled | Capacidade de aplicação de artefactos | Plano imutável, aprovação original e reverificação do estado atual |
| datafocus.mcp.ontology-published-query-enabled | Modelos publicados e consultas | Versão committed real e autorização da origem |
| 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 com delegação de publicação automática | Política original válida, confiança na chave pública, orçamento e permissão de publicação |
Estes nomes provêm da configuração e da implementação do r56; a possibilidade de ativação depende dos serviços associados e dos controlos (gates) originais de entrada em produção. Alterar apenas valores booleanos não supre processadores, bases de dados, orçamentos de validação ou políticas em falta. A visibilidade da extensão de entrada de conhecimento e das tarefas Pi depende dos componentes realmente instalados.
Proxy de periferia (edge)
Preservar Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name e o Origin aprovado. Definir o corpo do pedido, os tempos limite e o TLS conforme os requisitos reais do serviço; não encaminhar o /mcp público para a porta de administração nem para outro produto.
Verificação de entrada em produção
- O estado da descoberta anónima e das chamadas protegidas está conforme o esperado.
- Os utilizadores normais só descobrem o seu âmbito autorizado; após revogação, os pedidos seguintes são recusados.
- 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.
- Os registos e a documentação pública não contêm chaves privadas, Tokens, Cookies, palavras-passe 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.
O examples/flash_mcp.py é um cliente de protocolo mínimo que depende apenas da biblioteca padrão de Python. Não inicia sessão, não trata aprovações em nome de outrem e não invoca automaticamente ferramentas não visíveis; suporta protocolos modernos e antigos e termina com saídas distintas por camada: HTTP, JSON-RPC e erros de ferramentas. O Token é fornecido através do ambiente do processo, sem ser escrito em scripts ou ficheiros 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.jsonSubstituir primeiro os marcadores como ONTOLOGY_ID e TABLE_RESOURCE_ID no ficheiro de pedido pelos valores reais devolvidos pela autorização atual. O cliente recusa a execução se encontrar marcadores por substituir. O exemplo de SQL exige que o CSV associado tenha sido importado com os nomes de colunas originais; não é possível submeter diretamente sem o schema correspondente.
Outros cenários
- Ponto de entrada de negócio: usar --endpoint business e obter um novo Grant para /mcp/business.
- Cliente antigo: escolher --protocol 2025-11-25, executar primeiro initialize e depois chamar com o mesmo protocolo.
- Instruções incorporadas: usar resources ou read-resource para ler o URI real.
- Autoverificação offline: --self-test valida a construção de cabeçalhos modernos e metadados, sem precisar de Token e sem contactar o servidor do produto.
Limites do exemplo
O cliente é o ponto de partida do acesso ao protocolo; não gera automaticamente candidatos de modelação, não guarda perguntas e respostas nem executa publicações. Devolve o JSON original para que o agente de nível superior verifique o estado do negócio; não prometa ao utilizador 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ção da ontologia
Incorpore a página de conversação para utilizadores humanos no frontend de negócio, mantendo os limites de segurança do início de sessão 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, substituir por coordenadas reais autorizadas. Uma única ontologia pode ser indicada por path ou por um parâmetro query suportado; o modo all disponibiliza @ para selecionar as ontologias acessíveis ao utilizador atual. O skillId é apenas reencaminhado; não afirmar, com base nisso, que a orquestração de competências já é executável.
Autenticação e domínio
A página incorporada depende de uma sessão real iniciada no DataFocus e verifica /uc/status. Cookies entre sites, SSO, frame-ancestors de CSP e a configuração do gateway afetam a incorporação. Não aceita a inserção de um Bearer MCP no URL como canal de acesso sem início de sessão; as ligações externas outside, ainda não implementadas, não podem ser construídas manualmente com base em propostas de conceção.
Diferença entre MCP e iframe
| Modo | Utilizador | Identidade e resultado |
|---|---|---|
| Remote MCP | Integração de agente ou serviço externo | Grant OAuth e recibos estruturados das ferramentas |
| Conversa com o agente de ontologia em iframe | Utilizador final humano | Estado de sessão original e interface de conversa |
| MCP Apps | Cliente MCP com suporte para extensões | Recursos controlados e resultados de ferramentas atuais, não um substituto do início de sessão através de um iframe público |
Lista de verificação de aceitação da integração
Prove a cadeia de negócio completa numa instância real, em vez de apenas confirmar que as interfaces devolvem 200.
- Descoberta: obter as versões realmente suportadas, o catálogo de ferramentas atual e os recursos incorporados.
- Autorização: os utilizadores normais veem apenas as ontologias e os sistemas de negócio autorizados; as operações sem o âmbito necessário são recusadas.
- Estrutura de tabelas: nomes de apresentação reais, colunas, tipos e permissões completos.
- SQL: verificações de dimensão única, multidimensional, JOIN, data, TopN e truncamento de acordo com os critérios reais do negócio.
- Conhecimento: localização, texto integral original e elegibilidade para citação de factos consistentes; perguntas mistas com fundamentação simultânea em dados e documentos.
- Search: as verificações de modelo, init, sugestões, resultados, encerramento e integridade da memória intermédia são aprovadas.
- Análise e relatórios opcionais: estados reais de múltiplos ramos, paginação, alterações de permissões e cancelamento mantêm o comportamento original.
- Modelação opcional: candidatos, planos, aprovação original, aplicação efetiva e consultas de versão verificados fase a fase.
- Ações de negócio: hash de publicação, versão de destino, aprovação, idempotência e isolamento entre Grants verificados.
- Recuperação: após um timeout de rede, recuperar o estado original; após uma atualização da origem, as localizações antigas tornam-se inválidas e são utilizadas novas consultas.
Registo de resultados
Registar a versão da instância, a função do utilizador, o âmbito do Grant, a versão de configuração, as operações reais e os resultados. Marcar separadamente a autoverificação offline do cliente de protocolo, os valores offline esperados do exemplo CSV, a validação estática de Schema JSON e a verdadeira aceitação funcional online. Não extrapolar a aprovação de uma fase para a aprovação de todo o produto.
Recursos normativos e manutenção
Utilize os Schemas completos das ferramentas incluídos no manual e mantenha-os sincronizados com os resultados reais de descoberta da instância.
| Recursos | Conteúdo |
|---|---|
| reference/mcp-tool-catalog.json | 32 Schemas de entrada declarados do lado da ontologia e 8 do lado do negócio; algumas ferramentas incluem os Schemas de saída originais |
| reference/locales.json | 21 opções selecionáveis, 24 locales compatíveis e terminologia de UI |
| reference/search-keywords.json | 17 catálogos estáticos de palavras-chave com locale explícito |
| reference/analysis-contract-manifest.json | Restrições de versão relacionadas com análise, ramos, factos, recibos e relatórios |
| examples/ | CSV sintéticos, notas sobre critérios, SQL de Top3, resultados esperados e um cliente de protocolo mínimo |
Recursos de instruções incorporados
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 utilizador atual possua pelo menos uma das permissões de leitura correspondentes: metadata, search operate ou etl operate. Os documentos de ETL são uma referência estática entre produtos; as capacidades executáveis do Flash continuam limitadas ao que este reporta explicitamente.
Referências externas 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 os comportamentos condicionais deste produto baseiam-se na implementação do r56 e nos resultados atuais de descoberta da instância; não se deve equiparar o suporte genérico do protocolo à disponibilidade de todas as funcionalidades opcionais no servidor.
Manutenção e atualizações
Ao atualizar, redescobrir as ferramentas e as versões e comparar os Schemas de entrada, os contratos de saída e a configuração; os Grants antigos não adquirem automaticamente novos âmbitos. Manter referências, caches e recibos vinculados à versão da origem; após confirmar alterações incompatíveis, voltar a obter o contexto e não forçar a aplicação de localizações antigas a novos estados de negócio.
Referência de parâmetros das ferramentas — base e Search nativo
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfc_manual
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| names | array | Opcional ou condicionalmente obrigatório | Nomes explícitos a localizar, no máximo 32 por chamada. maxItems: 32 |
| action | string | Opcional ou condicionalmente obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: list, read, keywords, functions, etl_requests |
| locale | string | Opcional ou condicionalmente obrigatório | Locale explícito do catálogo de referência estático, não o idioma predefinido das consultas. |
| uri | string | Opcional ou condicionalmente obrigatório | URI do recurso incorporado listado 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 | Obrigatório | Significado e limites |
|---|---|---|---|
| data | object | Opcional ou condicionalmente obrigatório | Payload da ação original; consultar a tabela de descoberta de capacidades e de campos de ações. |
| action | string | Obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| data | object | Opcional ou condicionalmente obrigatório | Payload da ação original; consultar a tabela de descoberta de capacidades e de campos de ações. |
| action | string | Obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: capabilities |
dfc_ontologies
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| pageSize | integer | Opcional ou condicionalmente obrigatório | Número de itens por página; de acordo com 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 | Obrigatório | Significado e limites |
|---|---|---|---|
| resourceTypes | array | Opcional ou condicionalmente obrigatório | Conjunto de tipos de recursos a devolver. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| pageSize | integer | Opcional ou condicionalmente obrigatório | Número de itens por página; de acordo com 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 das ferramentas — tabelas, grafo e conhecimento
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfc_ontology_graph
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| 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 de consulta, ou objeto de consulta versionado exato correspondente à action. |
| limit | integer | Opcional ou condicionalmente obrigatório | Limite máximo de resultados devolvidos. minimum: 1; maximum: 100 |
| action | string | Obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da 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 cadeia de caracteres. |
| nodeKey | string | Opcional ou condicionalmente obrigatório | Chave de nó copiada dos resultados reais do grafo. |
| keyword | string | Opcional ou condicionalmente obrigatório | Palavra-chave de localização no grafo, não sintaxe de perguntas por palavras-chave. |
| nodeTypes | array | Opcional ou condicionalmente obrigatório | Filtro por tipo de nó. |
dfc_ontology_query
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| routeLocators | array | Opcional ou condicionalmente obrigatório | Localização de rota tipificada emitida pelo servidor, copiada na íntegra. maxItems: 20 |
| topK | integer | Opcional ou condicionalmente obrigatório | Limite de candidatos obtidos, sem garantia de cobertura completa. minimum: 1; maximum: 20 |
| queryMode | string | Opcional ou condicionalmente obrigatório | Modo de consulta de evidências selecionado conforme a enumeração da ferramenta. enum: vector, hybrid, graph |
| fanoutPlan | object | Opcional ou condicionalmente obrigatório | Plano restrito de pesquisa por ramos, conforme o Schema aninhado. |
| structuredPlan | object | Opcional ou condicionalmente obrigatório | Plano da tabela documental completa vinculado ao contrato do servidor; não é SQL. |
| knowledgeIds | array | Opcional ou condicionalmente obrigatório | ID de base de conhecimento presente no knowledgeBindings real. |
| query | string | Obrigatório | Texto de consulta, ou objeto de consulta versionado exato correspondente à action. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
dfc_knowledge_search
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| topK | integer | Opcional ou condicionalmente obrigatório | Limite de candidatos obtidos, 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 de base de conhecimento presente no knowledgeBindings real. |
| query | string | Obrigatório | Texto de consulta, ou objeto de consulta versionado exato correspondente à action. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| assetIds | array | Opcional ou condicionalmente obrigatório | IDs de ativos documentais atualmente permitidos. |
| retrievalStrategy | string | Opcional ou condicionalmente obrigatório | Estratégia de pesquisa realmente suportada. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| qdrantId | string / integer | Opcional ou condicionalmente obrigatório | Identificador de índice devolvido pela localização real. |
| pageNo | integer | Opcional ou condicionalmente obrigatório | Número da página real ou da paginação. |
| evidenceId | string | Opcional ou condicionalmente obrigatório | ID da evidência devolvido pela mesma localização de conhecimento. |
| action | string | Obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: chunk, document, page_context |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| documentId | string / integer | Opcional ou condicionalmente obrigatório | ID do documento da mesma localização. |
| radius | integer | Opcional ou condicionalmente obrigatório | Intervalo 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 | Obrigatório | Significado e limites |
|---|---|---|---|
| maxRows | integer | Opcional ou condicionalmente obrigatório | Limite de linhas devolvidas; não é um intervalo de classificação do cliente. minimum: 1; maximum: 200 |
| action | string | Obrigatório | Nome da operação. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: detail, query |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| id | string | Opcional ou condicionalmente obrigatório | ID real do recurso de tabela, não o nome físico nem o nome de apresentação. |
| sql | string | Opcional ou condicionalmente obrigatório | Uma única consulta Doris SQL só de leitura, dentro do âmbito da ontologia, com colunas de saída explícitas. |
Referência de parâmetros das ferramentas — análise e relatórios
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfc_analysis_ask
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| question | string | Obrigatório | Pergunta em linguagem natural ou pergunta de seguimento compatível. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito para resposta ou consulta; se omitido, aplica-se a regra da ferramenta correspondente. |
| sessionId | string | Opcional ou condicionalmente obrigatório | Localização real da sessão no mesmo Grant. |
dfc_analysis_refine
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| branchId | string | Opcional ou condicionalmente obrigatório | Localização do ramo estruturado emitida pelo servidor. |
| resultId | string | Obrigatório | Localização dos resultados de análise devolvidos originalmente. |
| question | string | Opcional ou condicionalmente obrigatório | Pergunta em linguagem natural ou pergunta de seguimento 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 | Alteração em linguagem natural ou filter_patch tipificado. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito para resposta ou consulta; se omitido, aplica-se a regra da ferramenta correspondente. |
| sessionId | string | Obrigatório | Localização real da sessão no mesmo Grant. |
| expectedRevision | integer | Obrigatório | Pré-condição de versão do resultado original ou do cabeçalho de negócio; pode ser null ao criar a questão. minimum: 1 |
| visualId | string | Opcional ou condicionalmente obrigatório | Localização de visualização vinculada ao ramo. |
dfc_analysis_page
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| branchId | string | Obrigatório | Localização do ramo estruturado emitida pelo servidor. |
| resultId | string | Obrigatório | Localização dos resultados de análise devolvidos originalmente. |
| pageNo | integer | Obrigatório | Número real da página ou da paginação. minimum: 1; maximum: 10000 |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| pageSize | integer | Obrigatório | Número de itens por página; de acordo com o limite do Schema. minimum: 1; maximum: 100 |
| sessionId | string | Obrigatório | Localização real da sessão no mesmo Grant. |
| expectedRevision | integer | Obrigatório | Pré-condição de versão do resultado original ou do cabeçalho de negócio; pode ser null ao criar a questão. minimum: 1 |
dfc_analysis_result_get
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| resultId | string | Obrigatório | Localização dos resultados de análise devolvidos originalmente. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| sessionId | string | Obrigatório | Localização real da sessão no mesmo Grant. |
dfc_analysis_cancel
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| resultId | string | Obrigatório | Localização dos resultados de análise devolvidos originalmente. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| sessionId | string | Obrigatório | Localização real da sessão no mesmo Grant. |
dfc_analysis_close
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| sessionId | string | Obrigatório | Localização real da sessão no mesmo Grant. |
dfc_report_create
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| goal | string | Obrigatório | Objetivo de 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 cadeia de caracteres. |
| language | string | Opcional ou condicionalmente obrigatório | Locale explícito para resposta ou consulta; se omitido, aplica-se a regra da ferramenta correspondente. |
| title | string | Opcional ou condicionalmente obrigatório | Título opcional do relatório. |
dfc_report_status
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| reportId | string | Obrigatório | Localização persistente do relatório no Grant atual. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
dfc_report_cancel
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| reportId | string | Obrigatório | Localização persistente do relatório no Grant atual. |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
Referência de parâmetros das ferramentas — modelação e tarefas originais
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfc_ontology_agent
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| 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 pedido do utilizador; mantenha-o idêntico entre context e submit. 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. Utilizar de acordo com a enumeração atual e os parâmetros correspondentes da ação. enum: start, status, cancel |
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| runId | string | Opcional ou condicionalmente obrigatório | ID da tarefa original da mesma ontologia e do mesmo Grant. |
| contractVersion | string | Obrigatório | Deve ser utilizada a versão exata de contrato realmente suportada. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
O objeto raiz de entrada desta ferramenta não tem campos; utilizar um objeto arguments vazio.
dfc_artifact_context
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| artifactType | string | Obrigatório | Tipo de artefacto ou de publicação de ontologia realmente ativado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Opcional ou condicionalmente obrigatório | Tipo de âmbito de recursos no contrato real do artefacto. |
| ontologyId | string | Opcional ou condicionalmente obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| projectId | string | Opcional ou condicionalmente obrigatório | ID do projeto na autorização atual. |
| artifactId | string | Opcional ou condicionalmente obrigatório | ID real do artefacto existente a editar. |
| instruction | string | Obrigatório | Texto do pedido do utilizador; mantenha-o idêntico entre context e submit. |
| variables | object | Opcional ou condicionalmente obrigatório | Objeto de variáveis fornecido de acordo com o contrato devolvido. |
| previewInput | object | Opcional ou condicionalmente obrigatório | Entrada de pré-visualização delimitada fornecida de acordo com o contrato. |
| viewport | object | Opcional ou condicionalmente obrigatório | Viewport de apresentação exigido pelo contrato original. |
dfc_ontology_table_schema
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| ontologyId | string | Obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| sourceAssetRef | string | Obrigatório | Referência estruturada a um ativo registado, por exemplo table:123. |
| fields | array | Obrigatório | Campos da origem atual com declarações de tipo explícitas opcionais. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| proposalId | string | Obrigatório | ID do candidato original criado no Grant atual. |
| candidateHash | string | Obrigatório | Hash exato do candidato emitido originalmente pelo servidor. |
| previewInput | object | Obrigatório | Entrada de pré-visualização delimitada fornecida de acordo com o contrato. |
dfc_artifact_status
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| proposalId | string | Opcional ou condicionalmente obrigatório | ID do candidato original criado no Grant atual. |
| planId | string | Opcional ou condicionalmente obrigatório | ID do plano de aplicação imutável. |
dfc_artifact_plan
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| proposalId | string | Obrigatório | ID do candidato original criado no Grant atual. |
| candidateHash | string | Obrigatório | Hash exato do candidato emitido originalmente pelo servidor. |
| expectedTargetVersion | integer | Obrigatório | Pré-condição real da versão de destino 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 | Obrigatório | Significado e limites |
|---|---|---|---|
| planId | string | Obrigatório | ID do plano de aplicação imutável. |
| planHash | string | Obrigatório | Hash devolvido pelo plano original. |
| approvalToken | string | Obrigatório | Materiais de aprovação emitidos pelo servidor original; é proibido gerá-los 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 | Obrigatório | Significado e limites |
|---|---|---|---|
| Configuração 1 / artifactType | string | Obrigatório | Tipo de artefacto ou de publicação de ontologia realmente ativado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Configuração 1 / scopeType | string | Opcional ou condicionalmente obrigatório | Tipo de âmbito de recursos no contrato real do artefacto. |
| Configuração 1 / ontologyId | string | Opcional ou condicionalmente obrigatório | ID real da ontologia dentro da autorização atual, preservado como cadeia de caracteres. |
| Configuração 1 / projectId | string | Opcional ou condicionalmente obrigatório | ID do projeto na autorização atual. |
| Configuração 1 / artifactId | string | Opcional ou condicionalmente obrigatório | ID real do artefacto existente a editar. |
| Configuração 1 / instruction | string | Obrigatório | Texto do pedido do utilizador; mantenha-o idêntico entre context e submit. |
| Configuração 1 / variables | object | Opcional ou condicionalmente obrigatório | Objeto de variáveis fornecido de acordo com o contrato devolvido. |
| Configuração 1 / previewInput | object | Opcional ou condicionalmente obrigatório | Entrada de pré-visualização delimitada fornecida de acordo com o contrato. |
| Configuração 1 / viewport | object | Opcional ou condicionalmente obrigatório | Viewport de apresentação exigido pelo contrato original. |
| Configuração 1 / contractVersion | string | Obrigatório | Deve ser utilizada a versão exata do contrato efetivamente suportada. |
| Configuração 1 / contextHash | string | Obrigatório | Hash do contexto completo devolvido por context. |
| Configuração 1 / baseArtifactHash | string | Obrigatório | Hash do artefacto base devolvido por context. |
| Configuração 1 / baseArtifactVersion | integer | Obrigatório | Versão base devolvida por context. minimum: 0 |
| Configuração 1 / candidate | object | Obrigatório | Candidato conforme o contrato atualmente devolvido. |
| Configuração 1 / clientRequestId | string | Obrigatório | Chave de idempotência do cliente, estável para o pedido do candidato atual. |
| Configuração 2 / artifactType | string | Obrigatório | Tipo de artefacto ou publicação da ontologia efetivamente ativado. enum: ONTOLOGY_RELEASE |
| Configuração 2 / contractVersion | string | Obrigatório | Deve ser utilizada a versão exata do contrato efetivamente 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 cadeia de caracteres. |
| Configuração 2 / candidateHash | string | Obrigatório | Hash exato do candidato emitido originalmente pelo servidor. |
| Configuração 2 / workspaceId | string | Obrigatório | Coordenadas reais do espaço de trabalho do candidato. |
| Configuração 2 / workspaceRevision | string | Obrigatório | Versão exata do candidato, sem utilizar latest. |
| Configuração 2 / releases | object | Obrigatório | Seleção da versão exata conforme o contrato de publicação da ontologia. |
| Configuração 2 / selection | object | Obrigatório | Fornece apenas coordenadas de seleção de negócio explícitas; não fornece provas de permissões nem 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 artefacto ou publicação da ontologia efetivamente ativado. enum: ONTOLOGY_RELEASE |
| Configuração 3 / Configuração 1 / contractVersion | string | Obrigatório | Deve ser utilizada a versão exata do contrato efetivamente 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 cadeia de caracteres. |
| Configuração 3 / Configuração 1 / workspaceId | string | Obrigatório | Coordenadas reais do espaço de trabalho do candidato. |
| Configuração 3 / Configuração 1 / resources | array | Obrigatório | Declarações do modelo original, compiladas 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 artefacto ou publicação da ontologia efetivamente ativado. enum: ONTOLOGY_RELEASE |
| Configuração 3 / Configuração 2 / contractVersion | string | Obrigatório | Deve ser utilizada a versão exata do contrato efetivamente 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 cadeia de caracteres. |
| Configuração 3 / Configuração 2 / workspaceId | string | Obrigatório | Coordenadas reais do espaço de trabalho do candidato. |
| Configuração 3 / Configuração 2 / resources | array | Obrigatório | Declarações do modelo original, compiladas 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 respetivo fecho de dependências. |
| Configuração 4 / artifactType | string | Obrigatório | Tipo de artefacto ou publicação da ontologia efetivamente ativado. enum: ONTOLOGY_RELEASE |
| Configuração 4 / contractVersion | string | Obrigatório | Deve ser utilizada a versão exata do contrato efetivamente 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 cadeia de caracteres. |
| Configuração 4 / domainRid | string | Obrigatório | RID real do domínio de negócio. |
| Configuração 4 / consumerScopes | array | Obrigatório | Âmbito exato de consumidores permitido 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 das ferramentas — entrada de conhecimento e âmbito
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfc_ontology_knowledge_input_propose
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| request | object | Obrigatório | Pedido de entrada de negócio original; conforme o Schema completo aninhado. |
| 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 da saída, o estado e os campos de autorização explicitamente definidos como false; não eleve por conta própria o significado de conclusão.
dfc_ontology_knowledge_input_preview
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| 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 cadeia de caracteres. |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade da saída, o estado e os campos de autorização explicitamente definidos como false; não eleve por conta própria o significado de conclusão.
dfc_ontology_knowledge_question_submit
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| questionRevision | $ref | Obrigatório | Versão explícita desta questão pendente de confirmação. |
| 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 cadeia de caracteres. |
| validUntil | $ref | Obrigatório | Fim da janela de validade da questão, em UTC. |
| expectedRevision | oneOf | Obrigatório | Pré-condição de versão do resultado original ou do cabeçalho de negócio; pode ser null ao criar a questão. |
| validFrom | $ref | Obrigatório | Início da janela de validade da questão, em UTC. |
Esta ferramenta possui um outputSchema nativo adicional. Verifique a integridade da saída, o estado e os campos de autorização explicitamente definidos como false; não eleve por conta própria o significado de conclusão.
dfc_ontology_business_scope_initialize
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| 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 cadeia de caracteres. 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 da saída, o estado e os campos de autorização explicitamente definidos como false; não eleve por conta própria o significado de conclusão.
Referência de parâmetros das ferramentas — área de trabalho de negócio
Nomes completos e campos de entrada, organizados por ferramenta para consulta.
As tabelas seguintes são uma referência de leitura dos campos de entrada das ferramentas atuais do r56. Para os tipos aninhados completos, oneOf, obrigatoriedade condicional, restrições de padrão e alguns Schemas de saída, consulte reference/mcp-tool-catalog.json; antes da submissão 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 internos da ação.
dfb_systems
O objeto raiz de entrada desta ferramenta não tem campos; utilizar um objeto arguments vazio.
dfb_system_describe
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| systemId | string / integer | Obrigatório | ID do sistema permitido por este Grant de negócio. |
dfb_query
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| systemId | string / integer | Obrigatório | ID do sistema permitido por este Grant de negócio. |
| queryKey | string | Obrigatório | Chave de consulta publicada devolvida por describe. |
| objectKey | string | Opcional ou condicionalmente obrigatório | Chave do objeto publicado. |
| pageSize | integer | Opcional ou condicionalmente obrigatório | Número de itens por página; de acordo com 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 estado de negócio ou estado do servidor. |
dfb_record
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| recordId | string / integer | Obrigatório | ID do registo de negócio cuja leitura é atualmente permitida. |
| systemId | string / integer | Obrigatório | ID do sistema permitido por este Grant de negócio. |
dfb_work_items
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| systemId | string / integer | Obrigatório | ID do sistema permitido por este Grant de negócio. |
dfb_action_plan
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| expectedRecordVersion | integer | Opcional ou condicionalmente obrigatório | Versão atual do bloqueio otimista do registo de destino. minimum: 1 |
| systemId | string / integer | Obrigatório | ID do sistema permitido por este Grant de negócio. |
| commandType | string | Obrigatório | Tipo de comando do contrato publicado. |
| canonicalIrHash | string | Obrigatório | Hash do IR canónico da publicação atual. |
| releaseId | string / integer | Obrigatório | ID real da versão do contrato publicado. |
| payload | object | Obrigatório | Payload conforme o contrato de comandos atual em describe. |
| releaseHash | string | Obrigatório | Hash real do contrato publicado. |
| targetRecordId | string / integer | Opcional ou condicionalmente obrigatório | Registo de destino real sobre o qual operar. |
| agentManifestHash | string | Obrigatório | Hash real do manifest de capacidades do agente. |
| planIdempotencyKey | string | Obrigatório | Chave de idempotência estável do plano de negócio. |
dfb_action_status
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| actionPlanId | string / integer | Obrigatório | ID do plano de ações detido pelo Grant de negócio atual. |
dfb_action_execute
| Parâmetro | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
| approvalToken | string | Opcional ou condicionalmente obrigatório | Materiais de aprovação emitidos pelo servidor original; é proibido gerá-los por conta própria. |
| actionPlanId | string / integer | Obrigatório | ID do plano de ações detido pelo Grant de negócio atual. |