Manuale di integrazione OT Flash Agent e MCP
Protocollo, autorizzazione, contratti degli strumenti e flusso di chiamata completo
Creare applicazioni dati e di conoscenza tracciabili utilizzando il Remote MCP pubblico di OT Flash r56. Questo manuale descrive OAuth, i messaggi di protocollo, il riferimento dei parametri di tutti gli strumenti dichiarati, le regole sulle evidenze, le capacità condizionali e i flussi di ripristino, e include un client eseguibile ed esempi con dati sintetici.
Sviluppatori Agent, ingegneri di integrazione e amministratori
Gli esempi allegati mantengono in cinese i nomi dei campi visualizzati. La traduzione dell'interfaccia e del testo esplicativo non modifica i nomi effettivi di tabelle e colonne, i valori di enumerazione, i nomi degli strumenti o i campi di protocollo.
Indice
- 1Ambito di integrazione dell'Agent e criteri di completamento
- 2Connessione rapida e individuazione delle capacità
- 3Individuazione, registrazione e autorizzazione OAuth
- 4Scope, confini delle risorse e permessi in tempo reale
- 5HTTP e messaggi moderni MCP
- 6Compatibilità con i client del protocollo legacy
- 7Scelta dello strumento corretto e del canale di evidenza
- 8Risorse dell'ontologia e tipi di ID
- 9Contratto di query e struttura delle tabelle Doris
- 10Top3 multidimensionale e gestione del troncamento
- 11Retrieval della conoscenza — testo originale completo e idoneità come evidenza
- 12Modelli e sessioni Search nativi
- 13Convenzioni su lingua e impostazioni regionali
- 14Analisi ibride e risultati interattivi
- 15Report visivi persistenti e MCP Apps
- 16Bozze di artifact, anteprima, piano e applicazione
- 17Contratti di creazione e pubblicazione dei candidati di ontologia
- 18Modelli pubblicati, query sui candidati e chiusura dei riferimenti
- 19Delega di attività all'Agent dell'ontologia
- 20MCP dell'area di lavoro business
- 21Input di conoscenza di business e domande da confermare
- 22Risposta, errori e retry sicuri
- 23Sicurezza dell'integrazione e confini di capacità
- 24Configurazione amministratore e interruttori condizionali
- 25Client eseguibile ed esempi di chiamata
- 26Incorporare l'interfaccia di dialogo dell'ontologia
- 27Elenco di verifica per l'accettazione dell'integrazione
- 28Risorse di riferimento e manutenzione
- 29Riferimento dei parametri degli strumenti: base e Search nativo
- 30Riferimento dei parametri degli strumenti: tabelle, grafo e conoscenza
- 31Riferimento dei parametri degli strumenti: analisi e report
- 32Riferimento dei parametri degli strumenti: modellazione e attività originali
- 33Riferimento dei parametri degli strumenti: input di conoscenza e ambito
- 34Riferimento dei parametri degli strumenti: area di lavoro business
Ambito di integrazione dell'Agent e criteri di completamento
Scegliere il punto di ingresso di autorizzazione e completare query, raccolta di evidenze o scritture controllate sulla base delle ricevute del server.
OT Flash r56 offre agli Agent esterni capacità di dati e conoscenza nell'ambito dell'ontologia tramite Remote MCP e fornisce un punto di ingresso separato per l'area di lavoro business. L'Agent deve determinare il lavoro eseguibile in base al tools/list effettivo, all'inputSchema, agli scope OAuth e ai permessi correnti sulle risorse; non può dedurre da un manuale statico che una distribuzione abbia tutte le funzioni opzionali abilitate.
| Punto di ingresso | Finalità | Confini |
|---|---|---|
| /mcp | Ontologia, tabelle dati, conoscenza documentale, Search nativo, nonché analisi e modellazione ad accesso condizionale | Intersezione tra i permessi dell'utente corrente e le risorse concesse con questa autorizzazione |
| /mcp/business | Individuazione dei sistemi business, query, piani d'azione, stato ed esecuzione | Autorizzazione separata dei sistemi business e contratti pubblicati |
| Pagina incorporata dell'Agent dell'ontologia | Uso del dialogo con l'ontologia in un'interfaccia per utenti umani | Richiede una sessione di login reale; non è un punto di ingresso per lo scambio di token MCP senza login |
Classificazione delle capacità
- Lettura di base: ontologia e risorse, localizzazione nel grafo, retrieval della conoscenza e testo originale completo, dettagli delle tabelle autorizzate e Doris SQL.
- Delega separata: dfc_search richiede search:operate e continua a utilizzare i permessi originali di utente e modello.
- Accesso condizionale: analisi, report persistenti, bozze e applicazione di artifact, query sui modelli di ontologia e attività delegate all'Agent.
- Capacità non disponibili: lo strumento dfc_etl di Flash restituisce solo le capabilities e non fornisce l'esecuzione Heavy ETL. AutoML e i punti di ingresso interni del workspace FocusCode non rientrano nell'API pubblica di Flash descritta in questo manuale.
Criteri di completamento
Per leggere fatti occorre ottenere una ricevuta di query o di testo originale completo effettivamente utilizzabile; la generazione di un candidato deve indicare che non è ancora stato applicato; la pubblicazione richiede una ricevuta reale APPLIED; l'annullamento deve distinguere tra richiesta e conferma. Il testo della risposta, un HTTP 200, la presa in carico da parte dello strumento o la descrizione “completato” del modello non provano da soli il successo di un'operazione di business.
Il file reference/mcp-tool-catalog.json allegato è il riferimento dichiarativo offline di r56: contiene anche le definizioni abilitate solo a condizione e non è il tools/list in tempo reale di alcun utente. Il catalogo completo comprende 28 strumenti core dell'ontologia, 4 estensioni condizionali del controller e 8 strumenti lato business, e non implica che siano tutti aperti per impostazione predefinita.
Connessione rapida e individuazione delle capacità
Partire dal dominio ufficiale dell'istanza e individuare con privilegi minimi gli strumenti effettivamente disponibili.
- Ottenere dall'amministratore l'indirizzo radice HTTPS ufficiale e l'ontologia o il sistema business a cui accedere. Non utilizzare i domini di esempio della documentazione per chiamate su dati di business reali.
- Configurare l'indirizzo del server MCP come https://flash.example.com/mcp; l'area di lavoro business utilizza /mcp/business dello stesso dominio.
- Avviare login e autorizzazione OAuth nel modo supportato dal client e verificare risorse e scope; non inviare nome utente e password tramite MCP.
- Eseguire l'individuazione o l'inizializzazione secondo la generazione di protocollo corrispondente, quindi leggere tools/list e le descrizioni delle risorse.
- Effettuare innanzitutto una piccola richiesta di sola lettura e verificare risultati strutturati ed errori; solo dopo eseguire l'obiettivo dell'utente.
Frammento di configurazione del client
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Questo frammento illustra l'intento di configurazione dell'indirizzo del server; la struttura effettiva del file di configurazione e il supporto OAuth dipendono dal client. Non inserire access_token, refresh_token, Cookie o password di amministratore reali in file pubblici.
Individuazione con protocollo 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": {}
}
}
}Controlli pre-integrazione
- L'indirizzo radice della risorsa, l'issuer OAuth e l'indirizzo pubblico del reverse proxy coincidono.
- Il client supporta la generazione di protocollo corrispondente, anziché inviare sempre initialize al punto di ingresso del nuovo protocollo.
- L'autorizzazione corrente è associata all'ontologia o al sistema business richiesto.
- Il token è valido e i nuovi scope opzionali sono stati esplicitamente autorizzati.
Individuazione, registrazione e autorizzazione OAuth
Utilizzare il codice di autorizzazione e PKCE, senza esporre all'Agent le credenziali di accesso del prodotto.
| Endpoint | Metodo | Funzione |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Individuazione della risorsa MCP dell'ontologia |
| /.well-known/oauth-protected-resource/mcp | GET | Individuazione compatibile tramite percorso della risorsa dell'ontologia |
| /.well-known/oauth-protected-resource/mcp/business | GET | Individuazione della risorsa MCP business |
| /.well-known/oauth-authorization-server | GET | Metadati del server di autorizzazione |
| /oauth/register | POST JSON | Registrazione dinamica di public client |
| /oauth/authorize | Form GET o POST | Login, selezione delle risorse e conferma dell'autorizzazione |
| /oauth/token | POST form | Scambio del codice di autorizzazione e refresh con rotazione |
| /oauth/revoke | POST form | Revoca del token |
| /oauth/grants | GET | L'utente che ha effettuato l'accesso visualizza le connessioni autorizzate |
| /oauth/grants/revoke | POST form | Revoca della connessione secondo il flusso della pagina originale |
Sequenza di autorizzazione
- Leggere i metadati delle risorse protette e i metadati del server di autorizzazione. Il 401 restituito a una richiesta senza token e l'header WWW-Authenticate indicano l'indirizzo di individuazione delle risorse.
- Registrare o utilizzare un'identità client. La registrazione dinamica dei public client in r56 usa token_endpoint_auth_method=none; il segreto client non può sostituire PKCE.
- Generare state e code_verifier casuali e calcolare il code_challenge S256.
- Aprire l'indirizzo authorize indicato nei metadati, passando response_type=code, client_id, redirect_uri esatto, scope, resource, state, code_challenge e code_challenge_method=S256.
- L'utente accede a DataFocus e seleziona l'ontologia o il sistema business. Il client non può preselezionare risorse a cui l'utente non ha accesso.
- Ricevere il callback, verificare state e issuer; scambiare il codice di autorizzazione utilizzando il code_verifier originale.
- Utilizzare l'access_token esclusivamente per l'autenticazione Bearer MCP. Il refresh segue il flusso OAuth originale; conservare in modo sicuro il refresh_token ruotato.
Esempio di registrazione
{
"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"]
}Il callback del client Web utilizza HTTPS; i client nativi possono utilizzare indirizzi di loopback supportati. Sia l'autorizzazione sia lo scambio del token richiedono la corrispondenza esatta con il callback registrato. Un Grant riguarda una sola protected resource: non mescolare scope dell'ontologia e scope dell'area di lavoro business nella stessa connessione.
Ciclo di vita del token
Sul server r56, per impostazione predefinita l'access token dura 3600 secondi, il refresh token 2592000 secondi e il codice di autorizzazione 300 secondi; la distribuzione può sovrascrivere questi valori. Il client deve basarsi su expires_in nella risposta del token e sugli errori effettivi, senza codificare in modo fisso i valori predefiniti. Aggiornare il token dopo il refresh; la revoca di ruoli, permessi su risorse o Grant fa sì che le chiamate successive vengano rifiutate.
Scope, confini delle risorse e permessi in tempo reale
Gli scope autorizzati delegano i permessi esistenti, non concedono elevazioni di ruolo e non condividono lo stato business tra Grant diversi.
| Scope | Capacità tipiche | Vincoli importanti |
|---|---|---|
| ontology.metadata:read | Ontologia, risorse, struttura delle tabelle | Ontologia e tabelle devono rientrare nell'autorizzazione e nell'ambito attualmente leggibile |
| ontology.graph:read | Ricerca nel grafo e nodi vicini | Restituisce informazioni di localizzazione, non evidenze fattuali |
| ontology.knowledge:read | Localizzazione nella conoscenza e testo originale completo | Conserva i permessi originali della knowledge base e dei documenti |
| ontology.table:query | Query SQL sulle tabelle dell'ontologia e query sui modelli pubblicati | La query sulle tabelle richiede anche lo scope metadata; origine effettiva e permessi sulle colonne restano in vigore |
| search:operate | Modelli e sessioni nativi per parole chiave | Delega esplicita e separata, eseguita secondo il modello originale e i permessi dell'utente su tabelle e colonne |
| etl:operate | Capabilities Flash ETL | Heavy ETL non disponibile |
| authoring.contract:read | Contratti di modellazione ad accesso condizionale | Richiede anche interruttori di funzionalità e risorse correlate |
| authoring.artifact:read | Lettura di candidati, piani ecc. con l'autorizzazione corrente | Vincolata al Grant e alle risorse del soggetto originale |
| authoring.artifact:draft | Invio di candidati, anteprime ecc. | Non autorizza esecuzione o pubblicazione |
| authoring.artifact:apply | Piani e applicazione controllati | Richiedono comunque il ruolo business originale, le policy e le approvazioni |
| execution.script:draft | Bozze di script specifici | Non autorizza l'esecuzione effettiva degli script |
| datasource.http:read / draft / test / import | Capacità sugli artifact delle sorgenti dati HTTP ad accesso condizionale | Interruttore indipendente per ciascuna voce e permessi originali |
Combinazioni di scope richieste per la lettura
dfc_table detail richiede ontology.metadata:read; query richiede inoltre ontology.table:query. dfc_ontology_query richiede entrambi gli scope di lettura graph e knowledge. dfc_knowledge_search/detail richiede knowledge. published_model/published_query usano table:query; candidate_query richiede inoltre authoring.artifact:read. Gli strumenti di analisi verificano anche gli scope di evidenza consentiti; i report persistenti richiedono metadata e table query.
Non codificare in modo fisso le autorizzazioni predefinite
L'insieme predefinito di scope dell'ontologia di r56 include table query; Search e ETL sono deleghe esplicite. In ultima analisi fanno fede i metadati di individuazione, la pagina di autorizzazione, gli scope effettivi del token e tools/list. Le affermazioni nella documentazione precedente secondo cui “per impostazione predefinita l'ontologia non include mai SQL” o “ci sono solo sei strumenti” non valgono per l'implementazione attuale.
Isolamento dello stato
Sessioni, report, candidati e piani d'azione hanno tutti un proprietario e un ambito propri. Il refresh dell'access token non trasferisce il lavoro del Grant originale a un altro Grant. Non unire alla connessione corrente sessionId, reportId, planId, token di approvazione o token di origine restituiti da un'altra connessione.
HTTP e messaggi moderni MCP
Inviare correttamente i metadati di ciascuna richiesta e gli header di routing corrispondenti, gestendo separatamente lo stato HTTP e i risultati degli strumenti.
| Voce | Comportamento r56 |
|---|---|
| Trasporto | Senza stato: Streamable HTTP, POST JSON-RPC |
| Identificativi supportati | 2026-07-28 e 2025-11-25 2025-06-18 2025-03-26 |
| Metodi moderni | server/discover tools/list tools/call resources/list resources/read, esposti in base alle capacità effettive |
| Header di sessione | Nessun Mcp-Session-Id assegnato |
| GET e DELETE | /mcp e /mcp/business restituiscono 405 |
| Notifiche SSE del server | Non fornite da questi due punti di ingresso MCP pubblici |
| Cache del catalogo | L'individuazione e gli elenchi moderni restituiscono ttlMs=60000 e cacheScope=private |
| Risultati ordinari | I risultati moderni includono resultType=complete e i metadati di identità del servizio |
Contenuti che devono corrispondere
- MCP-Protocol-Version coerente con io.modelcontextprotocol/protocolVersion nei params._meta.
- Mcp-Method coerente con il metodo JSON-RPC.
- Per tools/call, Mcp-Name corrisponde a params.name; per resources/read, l'header del nome corrisponde all'URI.
- Ogni richiesta moderna include l'oggetto io.modelcontextprotocol/clientCapabilities; fornire inoltre il clientInfo standard per facilitare l'identificazione del client.
Esempio di chiamata
{
"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": {}
}
}
}Gli header HTTP corrispondenti sono Mcp-Method: tools/call e Mcp-Name: dfc_ontologies. In tutti gli esempi ACCESS_TOKEN è un segnaposto. Non inserire il Bearer Token negli URL, nei parametri JSON o nelle chiavi di cache.
Lettura dei risultati
Elaborare prima lo stato HTTP, quindi verificare l'errore JSON-RPC; se è presente un result, controllare anche isError. I risultati degli strumenti andati a buon fine forniscono in genere structuredContent, insieme a un contenuto text contenente lo stesso JSON di business; leggere prima il canale strutturato ed evitare di aggregare due volte text e structuredContent come se fossero fatti indipendenti. Un HTTP 200 può comunque riportare un errore dello strumento.
Risorse pubbliche e UI
La risorsa di documentazione integrata non dipende da MCP Apps. Il punto di ingresso dell'area di lavoro business non ottiene per questo la risorsa di documentazione dell'ontologia. I client che supportano la visualizzazione dovrebbero individuare la UI corrispondente tramite le capacità effettive e i _meta degli strumenti, senza indovinare URI di risorse non restituiti.
Compatibilità con i client del protocollo legacy
Mantenere coerente la generazione di protocollo nei client che utilizzano ancora l'handshake di inizializzazione.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Inviare initialize e leggere la versione del protocollo e le capabilities negoziate dal server.
- Inviare le notifiche di completamento dell'inizializzazione necessarie in base al protocollo del client; le notifiche non restituiscono normali risultati di strumenti.
- Utilizzare tools/list per leggere gli strumenti attualmente autorizzati, quindi inviare tools/call.
- Mantenere header e messaggi coerenti con la generazione della richiesta corrente; non applicare il flusso legacy initialize o ping ai messaggi 2026-07-28.
Il protocollo legacy continua a utilizzare lo stesso Bearer/OAuth, gli stessi permessi e gli stessi contratti degli strumenti. Non implica che il server fornisca necessariamente connessioni SSE persistenti di tipo legacy o Mcp-Session-Id; il servizio pubblico r56 rimane senza stato.
Errori di protocollo
| Situazione | Risultato tipico | Soluzione |
|---|---|---|
| Header e messaggi moderni incoerenti | HTTP 400 JSON-RPC -32020 | Correggere header, metadati e nomi degli strumenti |
| Versione non supportata | -32022 con elenco delle versioni supportate | Selezionare un protocollo effettivamente supportato |
| Metodo sconosciuto | JSON-RPC -32601; le richieste moderne possono restituire HTTP 404 | Verificare la generazione del protocollo e il metodo |
| Parametri mancanti o non validi | JSON-RPC: errore di parametri oppure isError dello strumento | Correggere in base all'inputSchema effettivo |
Scelta dello strumento corretto e del canale di evidenza
Instradare in base al problema di business irrisolto, senza ripetere l'acquisizione delle evidenze con una catena di chiamate fissa.
| Attività | Strumento preferito | Evidenze necessarie al completamento |
|---|---|---|
| Individuazione di temi e risorse autorizzati | dfc_ontologies dfc_ontology_resources | Tipi effettivi degli ID delle risorse e ambito di visibilità corrente |
| Statistiche tabellari e TopN | dfc_table query | Ricevuta di esecuzione riuscita e evidenceRows completo |
| Consultazione di normative, contratti o report | dfc_ontology_query o knowledge search/detail | Testo originale completo, autorizzato e utilizzabile come fatto |
| Localizzazione di oggetti nel grafo | dfc_ontology_graph search/neighbors | Localizzare la fonte effettiva, quindi ottenere i fatti corrispondenti |
| Interazione originale per parole chiave | dfc_manual quindi dfc_search | Risultati effettivi nel modello e nei frame di business originali |
| Analisi ibrida e report | dfc_analysis_* o dfc_report_* | Stato reale di ciascun ramo strutturato e delle evidenze documentali |
| Modifica della visualizzazione o del modello dell'ontologia | dfc_authoring_* e strumenti artifact | Verifica separata di candidato, piano, approvazione e applicazione effettiva |
| Esecuzione di comandi di business | dfb_* di /mcp/business | Contratti pubblicati e ricevuta dell'ActionPlan originale |
Evitare chiamate non necessarie
Quando si dispone già di una struttura di tabella attuale, completa e autorizzata, non richiedere un nuovo detail a ogni query; quando si dispone già di una localizzazione affidabile e delle evidenze, non ripetere la stessa ricerca. Quando manca una dimensione necessaria, effettuare un'interrogazione supplementare circoscritta. Quando un errore è esplicitamente non ritentabile, colmare prima la lacuna, anziché sostituire la valutazione con un “riprova”.
Esclusioni di Flash
Le capabilities di dfc_etl possono restituire available=false insieme a ETL_NOT_INCLUDED_IN_OT_FLASH. La documentazione statica delle funzioni ETL integrate serve come riferimento trasversale tra prodotti e non dimostra che Flash abbia ETL installato, né consente all'Agent di passare automaticamente a Heavy o ad altri tenant per l'esecuzione.
Risorse dell'ontologia e tipi di ID
Ottenere prima le coordinate effettive delle risorse, per evitare di confondere nomi di archiviazione, ID di documenti e ID della knowledge base.
- Chiamare dfc_ontologies ed esplorare con page e pageSize le ontologie incluse in questa autorizzazione e ancora leggibili.
- Chiamare dfc_ontology_resources con un ontologyId reale; selezionare tra tables, answers, pinboards, documents e knowledgeBindings secondo necessità.
- Gestire separatamente la paginazione per ciascun tipo di risorsa. Il valore massimo di pageSize è 100; non dedurre l'intero insieme di risorse dalla prima pagina.
- Salvare il tipo dichiarato della risorsa e l'ID originale, e utilizzarli successivamente così come sono.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordinate | Origine | Non sostituibile con |
|---|---|---|
| ontologyId | Elenco delle ontologie autorizzate o contesto valido corrente | ID di un'altra ontologia |
| id della risorsa tabella | Elenco tables o contesto affidabile | physicalName o nome tabella visualizzato |
| tblDisplayName colDisplayName | Metadati correnti di tabelle e colonne | Identificatore fisico SQL ipotizzato |
| knowledgeId | knowledgeBindings o ricevuta effettiva di retrieval della conoscenza | id della risorsa documento |
| assetId documentId chunkId evidenceId | La stessa ricevuta effettiva di localizzazione | Campi assemblati a partire da risultati di localizzazione diversi |
| rid revisionId releaseId | Modello pubblicato o contesto del candidato lato server | ID generati autonomamente o latest |
Convenzioni di precisione
Tutti gli identificatori di risorsa a 64 bit vanno passati preferibilmente come stringhe decimali, senza conversione tramite Number in JavaScript. Alcuni Schema di business accettano string o integer, ma ciò non significa che si possa sacrificare la precisione degli interi. Anche gli opaque locator, UUID, gli hash e i token monouso vanno conservati così come sono.
Contratto di query e struttura delle tabelle Doris
Eseguire query SQL di sola lettura sulle tabelle autorizzate, preservando la semantica dell'output, i valori esatti e la completezza.
Lettura della struttura
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}detail utilizza un ID reale della risorsa tabella. Verificare schemaComplete, tblDisplayName, il colDisplayName in columns e il sqlDataType autorevole, nonché il queryContract restituito. dataType è solo una mappatura di compatibilità; il nome fisico di archiviazione non è il nome di tabella da usare nella SQL.
Esecuzione della query
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}Vincoli SQL
- Utilizzare i nomi di tabella e di colonna visualizzati, racchiudendo gli identificatori tra virgolette doppie. La richiesta è una query Doris di sola lettura nell'ambito dell'ontologia.
- Elencare esplicitamente gli output; SELECT * e table.* sono vietati: non possono essere usati per aggirare, tramite colonne fisiche, i permessi sulle colonne registrate.
- I join utilizzano JOIN ... ON espliciti; NATURAL JOIN e JOIN USING vengono rifiutati.
- Sono ammesse espressioni di sola lettura legittime come aggregazioni multidimensionali, CTE, finestre, CASE, COUNT(DISTINCT ...); il fatto che la validazione semantica non copra un'espressione non equivale a vietarne l'esecuzione.
- Completare prima in SQL aggregazioni, ordinamenti e classifiche, quindi applicare il limite sui risultati. maxRows vale 100 per impostazione predefinita, con un massimo di 200.
Date e fusi orari
| Tipo o destinazione | Forma | Nota |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) e CURRENT_DATE | Non presupporre che un letterale di testo sia di tipo data |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) e CURRENT_TIMESTAMP | Verificare il fuso orario della sorgente e quello della sessione |
| Tempo relativo | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Usare per date e timestamp le funzioni correnti corrispondenti |
| Raggruppamento temporale | YEAR(column) oppure DATE_TRUNC(column, 'month') | Usare un alias univoco per ogni output; fa fede queryContract |
Il DATE('now', ...) di SQLite non è il contratto data Doris di questo punto di ingresso. Non trasferire nella SQL online il metodo di verifica offline con SQLite usato negli esempi della documentazione.
Leggere la ricevuta di query v8
evidenceRows è l'unico canale dell'Agent verso i dati di riga; i raw data non sono accessibili all'Agent. I numeri SQL sono codificati come stringhe JSON decimali esatte; determinarne valore numerico e tipo di business tramite resultColumnContracts, senza interpretare i numeri codificati in JSON come VARCHAR solo perché sono stringhe. Leggere executionReceipt, le informazioni su completezza e troncamento e conservare le informazioni di origine come evidenceRowsSha256.
Gli output di query con una ricevuta di esecuzione citabile possono essere citati così come sono; solo la semantica verificata lato server autorizza successivi calcoli deterministici di secondo livello. Non dedurre dalla sola denominazione dei campi significati come “saldo cumulato”, “valore di fine periodo”, “valuta” né aggiungere unità per conto proprio. Risultati con zero righe, errori o troncamenti non devono essere descritti come statistiche complete.
Top3 multidimensionale e gestione del troncamento
Rispondere alle domande di classifica tramite aggregazioni e funzioni finestra lato server, senza ricalcoli su risultati incompleti.
Il file allegato examples/top3.sql usa la tabella di esempio: aggrega prima per 区域, 类别 e 产品, quindi esegue ROW_NUMBER all'interno di ciascun 区域 e 类别, usando il nome del 产品 come ordinamento stabile in caso di parità di importo. Una richiesta con maxRows=100 è sufficiente per le 36 righe dell'esempio; per altri dati di business valutare in base al numero reale di gruppi.
- Ottenere la struttura reale e il criterio di calcolo corrente, definendo valuta (币种), periodo, stato dell'ordine (订单状态) e regole di parità.
- Inviare la SQL di aggregazione e classifica lato server. Non limitarsi a interrogare prima il totale di 区域 per poi usarlo come classifica per 类别 e 产品.
- Verificare il contratto delle colonne di output e gli evidenceRows effettivi, confermando che i risultati restituiti coprano tutti i gruppi necessari.
- In caso di troncamento, eseguire query delimitate per partizione, entro i limiti supportati dal server, ad esempio ottenendo il Top3 completo separatamente per ciascun 区域; mantenere ogni volta lo stesso criterio di calcolo.
- Se nel frattempo la sorgente cambia, interrogare di nuovo e dichiarare esplicitamente la nuova versione, senza mescolare versioni di dati diverse o cursori non più validi.
Ripristino dopo errori
In caso di TABLE_SCHEMA_INCOMPLETE occorre correggere o ottenere la struttura completa; gli errori come ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID si gestiscono secondo errorCode, retryable e remediation restituiti. Non affermare che “tutte le GROUP BY multidimensionali o le funzioni finestra sono vietate” e non inventare classifiche in assenza di risultati di query.
Retrieval della conoscenza — testo originale completo e idoneità come evidenza
Separare localizzazione, lettura e citazione dei fatti, conservando provenienza e completezza.
Due percorsi comuni
| Percorso | Finalità | Punti chiave |
|---|---|---|
| dfc_ontology_query | Retrieval nella conoscenza associata all'ontologia, eventualmente combinato con l'instradamento tramite grafo | Verificare gli answerContextItems canonici completi e l'idoneità come evidenza |
| dfc_knowledge_search → chunk dfc_knowledge_detail | Localizzare con una ricerca esplicita, quindi leggere l'intero testo del frammento selezionato | L'anteprima di ricerca non costituisce un fatto; leggere il testo originale completo dello stesso risultato di localizzazione |
{"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>"
}}Condizioni per l'uso come fatto
- Verificare l'ACL corrente, la completezza del contenuto e il canonicalFactEligible, il citationEligible o il contratto di esecuzione corrispondente dichiarato dal server.
- Il contenuto completo è vincolato al contentSha256. Troncamenti, omissioni per budget o contenuti di bassa qualità vanno trattati secondo i campi effettivi.
- I metadati del documento, page_context, le localizzazioni nel grafo, i riassunti di retrieval e le anteprime non sostituiscono il testo canonico originale.
- Copiare preferibilmente evidenceId; quando servono chunkId e documentId, devono provenire dallo stesso risultato di localizzazione, senza combinarli né inventarli.
Instradamento tramite grafo
Il risultato di search/neighbors è un'informazione di localizzazione. Passare alla query sull'ontologia esclusivamente gli oggetti routeLocator restituiti integralmente dal server, inclusi binding, versione e campi di attestazione. Non incapsulare autonomamente un assetId o un knowledgeId come locator emesso dal server, né rinviare attestazioni di provenienza dichiarate dal modello.
Ripristino di documenti strutturati
Il structuredPlan di dfc_ontology_query serve esclusivamente al ripristino vincolato e alla verifica deterministica delle tabelle in documenti irregolari. Usare il piano dichiarato dal server solo dopo che sono stati restituiti executionContractSha256, tableIndex correnti, le colonne e la tabella completa. Le normali tabelle di business importate devono passare per dfc_table SQL; non trattare il ripristino di tabelle Markdown come un canale per aggirare l'autorizzazione alle query sulle tabelle.
Strategia di retrieval
knowledgeIds di norma viene omesso per coprire i binding attualmente abilitati; quando viene passato, utilizzare solo gli ID reali delle knowledge base presenti in knowledgeBindings. Non usare l'ID di una risorsa documento come ID di knowledge base. Per ogni questione ancora aperta effettuare una nuova ricerca delimitata, evitando retrieval identici che non apportano nuove evidenze.
Modelli e sessioni Search nativi
Tramite dfc_search, utilizzare il protocollo per parole chiave di Rust Search e attendere lo stato finale dei frame di business originali.
Leggere prima le istruzioni, poi individuare le capacità
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search richiede un search:operate esplicito. Incapsula il WebSocket originale per le parole chiave, senza riscrivere le parole chiave come richieste SQL o LLM. La sessione è vincolata a tenant, utente, Grant, client e modello correnti, e a ogni operazione vengono ricontrollati i permessi originali su tabelle e colonne.
Flusso minimo di sessione
{"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 utilizza da 1 a 100 veri ID di tabelle autorizzate, oppure model_read legge un sourceToken già posseduto dall'utente.
- open restituisce solo initializationSent; eseguire prima poll, leggere la risposta di init originale e confermarne l'esito positivo.
- Leggere assist e suggerimenti, quindi inviare un message originale supportato. Nelle query datas, isNl è fissato a false dal wrapper.
- Leggere continuativamente i frames, distinguendo suggerimenti, parsing, ricezione e risultato finale di business.
- Al termine eseguire close; per annullare usare cancel e verificare in base allo stato reale dell'attività se è stata effettivamente interrotta.
| action | data | Significato |
|---|---|---|
| capabilities | Omesso o oggetto vuoto | Legge azioni, comandi, TTL e note sul trasporto |
| model_create | Array tableIds | Crea un modello autorizzato per l'utente corrente |
| model_read | sourceToken | Legge il modello, filtrando colonne non autorizzate e configurazioni di sorgenti sensibili |
| open | sourceToken e language opzionale | Stabilisce una sessione nativa e invia init |
| request | sessionId e message | Invia un messaggio del protocollo originale type/datas |
| poll | sessionId e waitMillis da 0 a 30000 | Preleva i frame correnti dal buffer con eventuale attesa limitata |
| cancel close | sessionId | Chiude la sessione nativa; non consente di affermare uno stato terminale BI |
Comandi originali supportati
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteMaiuscole/minuscole dei comandi e struttura dei datas seguono le capabilities correnti e il protocollo della sessione originale. Non aggiungere a request azioni inesistenti; ad esempio, l'ortografia di disambiguite deve essere mantenuta secondo il protocollo effettivo. Ogni messaggio ha un massimo di 256 Ki caratteri.
Sessioni e completezza
Il TTL della sessione è di 10 minuti e la sessione viene conservata solo finché il processo corrente è attivo; non è un'attività ripristinabile in modo persistente. Il buffer contiene al massimo 256 frame ed è soggetto a un limite di memoria; con bufferOverflow=true non trattare i frame già prelevati come risultato completo. Dopo un errore di trasporto, eseguire prima poll sulla sessione originale, senza reinviare alla cieca query potenzialmente già eseguite.
Il wrapper corrente non offre salvataggio di risposte o pinboard, lettura/scrittura della cronologia né ripristino di contesti arbitrari. L'esistenza di exportContext non implica la possibilità di ripristinare contesti arbitrari. Per salvare i risultati, utilizzare le effettive capacità sulle risorse originali esposte dall'istanza, senza inventare action.
Convenzioni su lingua e impostazioni regionali
Mantenere i confini tra locale della UI, dizionario di query, lingua di restituzione e nomi dei campi originali.
La priorità è: lingua richiesta esplicitamente, lingua del sistema applicativo, locale del nodo di esecuzione effettivo. Valori omessi, null, stringhe vuote e spazi non comportano un fallback fisso al cinese. I valori di regione in languageRegistry vanno mantenuti con precisione; en-GB, fr-CA, pt-BR, es-US e ar-AE non devono essere accorpati arbitrariamente in un'altra regione.
| Lingua o regione | Locale della query | Descrizione |
|---|---|---|
| Cinese semplificato, cinese tradizionale | zh-CN zh-Hant | Le regole originali del cinese differiscono dal catalogo del cinese tradizionale |
| Inglese USA, UK, Australia, Canada | en-US en-GB en-AU en-CA | Pacchetti UI/parole chiave condivisibili, metadati regionali conservati |
| Tedesco, italiano, russo | de-DE it-IT ru-RU | Secondo i suggerimenti della sessione corrente |
| Spagnolo di Spagna e America Latina | es-ES es-US | L'ID regione del prodotto è es-US |
| Francese di Francia e Canada | fr-FR fr-CA | Gli ID regione non vengono accorpati |
| Portoghese di Portogallo e Brasile | pt-PT pt-BR | Cataloghi e convenzioni regionali conservati separatamente |
| Olandese, danese, norvegese, finlandese, svedese | nl-NL da-DK nb-NO fi-FI sv-SE | Il norvegese è Bokmål |
| Giapponese, coreano | ja-JP ko-KR | Non segmentare autonomamente le parole in base agli spazi come in inglese |
| Arabo di Arabia Saudita ed Emirati Arabi Uniti | ar-SA ar-AE | Le descrizioni dell'interfaccia supportano RTL; gli identificatori di protocollo non vengono invertiti |
Uso del catalogo delle parole chiave
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}Il catalogo statico delle parole chiave di dfc_manual include solo i locale esplicitamente elencati; in caso di omissione si usa il riferimento inglese: si tratta di un valore predefinito di riferimento, non di una regola di parsing della lingua della query. Quando una variante regionale non dispone di un catalogo statico, ottenere i suggerimenti effettivi tramite l'assist della sessione corrente, senza inventare alias o risultati di fallback. Il parametro names accetta al massimo 32 elementi per chiamata.
Contenuti da non tradurre
- Tabelle, colonne, valori di enumerazione, nomi dei clienti, nomi di formule e altre stringhe reali del modello.
- Nomi degli strumenti, action, scope, campi dello Schema, codici di errore e valori di stato.
- ID delle risorse, hash, locator opachi e riferimenti emessi dal server.
Ad esempio, una domanda in tedesco può interrogare la colonna visualizzata in cinese “销售金额”. Rinominarla con un nome di colonna tedesco produrrebbe un identificatore diverso, non una traduzione dell'interfaccia. Dopo un cambio di lingua, reinizializzare o aggiornare la sessione secondo il protocollo originale e recuperare di nuovo suggerimenti e candidati di disambiguazione.
Analisi ibride e risultati interattivi
Negli strumenti di analisi ad accesso condizionale, conservare autorizzazione, versione, ramo e stato delle evidenze.
dfc_analysis_* è controllato da datafocus.mcp.analysis.tools.enabled. La parte strutturata continua a passare per le query autorevoli di Search e la policy di riga corrente; per la parte documentale si riottiene il testo originale completo con l'ACL corrente. Non sono punti di ingresso per SQL libero, istruzioni arbitrarie o iniezione di filtri arbitrari.
| Strumento | Finalità | Coordinate necessarie |
|---|---|---|
| dfc_analysis_ask | Pone una domanda di analisi in linguaggio naturale | ontologyId question; facoltativi: language, sessionId |
| dfc_analysis_result_get | Legge i risultati già restituiti | ontologyId sessionId resultId |
| dfc_analysis_refine | Chiede approfondimenti o modifiche in base all'ultimo risultato completo | Risultato originale, expectedRevision e chiave di idempotenza stabile |
| dfc_analysis_page | Ottiene una pagina di un ramo lato server | Ramo originale e versione del risultato, pageNo pageSize |
| dfc_analysis_cancel | Annulla un risultato ancora in elaborazione | Sessione e risultato originali |
| dfc_analysis_close | Rilascia una sessione non più in elaborazione | Sessione originale |
Avvia l'analisi
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Leggere i valori sessionId, resultId, lo stato e la revision restituiti; se necessario, continuare a leggere il risultato originale.
- Verificare uno per uno stato, completezza, policy di riga e origini di ciascun ramo strutturato; il completamento di un singolo ramo non implica che l'intera analisi sia completa.
- Verificare le evidenze documentali, il registro dei fatti, l'idoneità alla citazione e i limiti. Le narrazioni generate dal modello non possono elevare da sole l'idoneità delle evidenze.
- Per un approfondimento, basarsi sull'ultimo risultato completo e passare expectedRevision; per ritentare la stessa modifica riutilizzare la stessa chiave di idempotenza.
- Prima di chiudere, confermare che la sessione non sia più in elaborazione; annullare e chiudere sono azioni diverse.
Filtraggio e impaginazione controllati
filter_patch utilizza branchId, fieldRef, valueRef e gli operatori consentiti forniti dal server; il filtro tipizzato corrente dichiara solo EQ. È vietato sostituire i riferimenti opachi con SQL grezzo, tableId, columnId o con un albero di filtri costruito arbitrariamente dal client. Per l'impaginazione, pageNo parte da 1, con un massimo di 10000; pageSize ha un massimo di 100.
Suggerimenti sulle capacità e comportamento
Le annotations degli strumenti sono suggerimenti per il client, non autorizzazioni di sicurezza. Alcuni modelli generici utilizzano readOnlyHint, che non sostituisce la valutazione dell'azione effettiva; l'annullamento, la chiusura e la creazione di report modificano i rispettivi stati di lavoro. Agire sempre secondo la semantica dello strumento, gli obiettivi dell'utente e i permessi lato server.
Report visivi persistenti e MCP Apps
Creare report ripristinabili e leggerne risultati e interfacce interattive in base ai permessi correnti.
dfc_report_* è controllato da datafocus.mcp.analysis.report-tools.enabled e richiede gli scope metadata e table query. A differenza delle sessioni Search interne al processo, i report utilizzano un reportId persistente; persistente non significa che i permessi non vengano più verificati.
{"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>"
}}Flusso di lavoro
- Alla creazione, utilizzare un idempotencyKey stabile, lungo da 8 a 128 caratteri supportati.
- Salvare reportId, eseguire il polling dello status e verificare gli stati effettivi come completato, non riuscito, parzialmente completato o annullato.
- Alla lettura dei risultati, verificare i rami strutturati, le visualizzazioni, le origini dei fatti, le citazioni documentali e la completezza.
- Per annullare un report non completato, utilizzare il reportId originale; non creare un altro report al posto dell'annullamento.
- Dopo un timeout di rete, leggere prima lo stato del report originale; la ripetizione con la chiave di idempotenza originale deve mantenere lo stesso intento di business.
MCP Apps
I client che supportano le estensioni UI leggono le pagine dei report tramite il _meta degli strumenti e l'individuazione effettiva delle risorse. La pagina del report persistente corrispondente a r56 è ui://datafocus/analysis-report/v16/index.html; l'analisi interattiva utilizza i riferimenti alle risorse lato server appropriati; il client non deve codificare in modo fisso valori in sostituzione di quelli restituiti dagli strumenti. Senza estensione UI, i risultati strutturati restano leggibili.
Binding dell'origine
La lettura dei report riverifica il Grant, l'ontologia, il binding all'Origin della richiesta e i permessi correnti sulle tabelle. Le integrazioni cross-origin del browser devono utilizzare origin effettivi approvati; il client non deve aggirare il binding falsificando l'Origin. Un vecchio reportId non è un collegamento pubblico di lunga durata né una credenziale di accesso tra utenti.
Bozze di artifact, anteprima, piano e applicazione
Affidare i contenuti generati al server originale per normalizzazione, validazione e approvazione, senza consentire al modello di modificare direttamente le risorse di produzione.
Gli strumenti artifact richiedono l'abilitazione della funzione authoring, un artifact type effettivo, gli scope pertinenti e i permessi originali di scrittura da amministratore. Per impostazione predefinita sono configurati i tipi CONTROL_PANEL_SPEC e VIEW_SPEC; gli altri tipi, per moduli, origini HTTP o script, sono soggetti anche a configurazioni separate. Flash non ha AutoML, pertanto i tipi correlati non sono elencati come artifact disponibili in questa versione.
- dfc_authoring_capabilities legge i contratti e le azioni disponibili per il Grant corrente.
- dfc_artifact_context ottiene il contesto delimitato, contractVersion, contextHash, baseArtifactHash e baseArtifactVersion.
- Generare il candidato nel client in base al contratto reale, senza eseguirne il codice.
- dfc_artifact_submit invia il contesto originale e il candidato, mantiene l'instruction identica e utilizza un clientRequestId stabile.
- Leggere proposalId, candidateHash, la verifica e l'anteprima; in presenza di errori effettivi, rivedere il candidato senza simulare un esito positivo lato server.
- Quando serve una nuova anteprima, utilizzare dfc_artifact_preview e lo stesso hash del candidato.
- dfc_artifact_plan crea un piano immutabile, utilizzando il candidato reale, la versione di destinazione e la chiave di idempotenza.
- Gestire l'approvazione tramite l'interazione originale o una policy già autorizzata, quindi chiamare dfc_artifact_apply; solo la ricevuta APPLIED attesta l'applicazione effettiva.
Richiesta di contesto minima
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC utilizza il projectId attualmente autorizzato; per modificare un artifact esistente, utilizzare il artifactId effettivo. I campi variables, previewInput, viewport e simili vengono forniti secondo il contratto restituito, senza inventare la struttura interna del candidato.
Concorrenza e retry
Il piano vincola la versione di destinazione, l'hash del candidato e la chiave di idempotenza. Se la destinazione cambia, il vecchio piano non può più essere applicato; rileggere il contesto e gestire il conflitto effettivo. Un timeout di trasporto non prova un fallimento: usare prima dfc_artifact_status per interrogare il proposalId o il planId originale. READY non è APPLIED.
Approvazione e policy automatiche
I piani di artifact generici richiedono l'approvazione umana originale. I piani conformi alla policy di pubblicazione automatica dell'ontologia vengono gestiti secondo approvalMode, senza chiedere all'utente di firmare un'ulteriore approvazione inventata dall'Agent. approvalToken è materiale emesso dal server e non può essere sostituito da una stringa scritta dall'Agent; il inputSchema effettivo e la ricevuta del piano determinano i campi obbligatori.
Contratti di creazione e pubblicazione dei candidati di ontologia
Utilizzare dichiarazioni di ontologia e configurazioni di pubblicazione con versioni indipendenti; non applicare alla pubblicazione dei modelli i contratti degli artifact di visualizzazione ordinari.
Creazione del candidato
Il contenitore di ontologia deve già esistere ed essere compreso nel Grant. Utilizzare dfc_ontology_table_schema per verificare i campi delle origini strutturate correnti e l'impronta del Binding v4; per i campi è possibile fornire solo sourceField affinché il tipo venga rilevato automaticamente. Una dichiarazione esplicita DECIMAL richiede la precisione e le cifre decimali correnti; gli altri tipi non includono questi due campi.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Candidati e configurazione di pubblicazione
| Contratto | Finalità | Confini critici |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Creazione del candidato da dichiarazioni locali | Origini realmente autorizzate, compilazione lato server, non accetta attestazioni di completamento |
| ontology-workspace-create-mcp-submit-v2 | Combinazione di dichiarazioni locali e riferimenti esatti già pubblicati | Fornire releaseSelections esatte e le dipendenze della chiusura |
| ontology-publication-mcp-submit-v1 fino a v3 | Associazione di un candidato esistente alla richiesta di piano di pubblicazione | Coordinate esplicite; destinazione, origine, approvazione e verifica vengono ricostruite dal server |
| ontology-publication-mcp-submit-v4 fino a v6 | Configurazioni correlate alla pubblicazione automatica abilitate separatamente | Utilizzo solo quando capabilities e schema effettivo lo dichiarano |
| ontology-initial-activation-retirement-submit-v1 | Operazioni controllate di attivazione iniziale e ritiro | Piano separato, nuova approvazione umana e ambito esatto |
Sequenza di pubblicazione
- Ottenere per il candidato corrente workspaceId, workspaceRevision, candidateHash e le origini effettive.
- Scegliere la versione del contratto in base alle capacità del server; inviare le coordinate come releases e selection, senza allegare campi che si dichiarino “approvato” o “convalidato”.
- Conservare il proposalId e l'idempotencyKey originale, restituiti da submit. submit e MODEL_PLAN sono fasi diverse della stessa richiesta.
- Chiamare dfc_artifact_plan, utilizzando il candidato originale, la versione di destinazione e la stessa chiave di idempotenza.
- PLANNING_INCOMPLETE indica solo che non è ancora stato formato un piano valido; VALIDATION_UNSATISFIED indica che la verifica corrente presenta ancora lacune, da gestire secondo nextAction.
- Dopo il successo del piano, proseguire secondo HUMAN_REQUIRED o POLICY_AUTO, utilizzando l'approvazione e le capacità di pubblicazione originali.
- Confermare il risultato con la ricevuta APPLIED e con la successiva lettura effettiva del modello pubblicato e una query autorizzata.
Timeout e ripristino
Dopo il timeout di PLAN, leggere il proposalId originale. MODEL_PLAN_SUBMITTED è una richiesta non completata; MODEL_PLAN_COMPLETED indica di ripristinare la ricevuta originale con le coordinate e la chiave originali, non di far creare al client una nuova richiesta. Le lacune di verifica nello stato finale non possono diventare una pubblicazione convalidata cambiando chiave o inviando di nuovo.
Permessi di business umani
L'instruction e le dichiarazioni fornite dall'Agent sono input dell'Agent, non firme di policy umane. MODEL_AUTHOR, MODEL_PUBLISH, la delega alla pubblicazione automatica, la conferma di business, l'attendibilità delle chiavi pubbliche, i budget e le ACL delle origini continuano a essere determinati dai meccanismi originali. Non sostituire questi fatti con campi lato client.
Modelli pubblicati, query sui candidati e chiusura dei riferimenti
Utilizzare la conoscenza di business pubblicata in base a versioni esatte e preservare la natura provvisoria dei candidati non pubblicati.
published_model, published_query e candidate_query di dfc_ontology_graph sono configurazioni strutturate ad accesso condizionale, non sinonimi del normale search/neighbors. L'autorizzazione si basa su table query e sui permessi di lettura per la modellazione necessari; la visibilità nel grafo non sostituisce i permessi sulle tabelle.
Lettura del modello pubblicato
- Quando l'enumerazione action dello strumento include effettivamente published_model, inviare il releaseId committed reale.
- v1 restituisce template di query autorizzate; v2 aggiunge i riferimenti esatti PERSISTED e releaseSelections; v3 aggiunge i riferimenti alle dipendenze, il domainRef esatto e template di binding compatti.
- Selezionare oggetti, proprietà, Binding, scope e versioni dai valori effettivamente restituiti, senza generare RID né usare latest.
- Inviare per published_query la query tipizzata fissa; i risultati devono comunque superare le autorizzazioni correnti su origini e campi.
Query sui candidati
candidate_query utilizza il workspaceId effettivo, revision, candidateHash e le dichiarazioni del candidato. In caso di combinazione con riferimenti pubblicati, usare le corrispondenti coordinate tipizzate LOCAL/PERSISTED v2 e la selezione esatta. I risultati sui candidati restano sempre non pubblicati e provvisori e non vanno considerati conoscenza confermata dall'azienda.
Manutenzione parziale e chiusura
Selezionare solo le dipendenze transitive necessarie alla radice del candidato e garantire che ogni riferimento pubblicato abbia un releaseSelections esatto. Copiare il contenuto pubblicato, inviare solo un insieme di ID o estendere la selezione a tutte le risorse storiche non sostituisce la verifica delle dipendenze e delle origini correnti.
Le query di queste action sono oggetti tipizzati con versione e non accettano SQL, ID di tabelle fisiche o nomi di tabelle di origine al posto dei riferimenti di business. I template di metadati e i risultati del grafo non hanno di per sé idoneità come riferimenti fattuali.
Delega di attività all'Agent dell'ontologia
Riprendere il lavoro con attività persistenti e il Grant originale; non trattare le istruzioni dell'Agent come approvazioni umane.
dfc_ontology_agent viene mostrato solo quando il Pi Runtime effettivo e i permessi pertinenti sono disponibili. QUERY utilizza le capacità di lettura; AUTHORING richiede inoltre un ruolo di modellazione e lo scope authoring corrispondente. Non espone un altro motore di esecuzione privo di vincoli.
{"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>"
}}Set di parametri rigoroso
start utilizza contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel utilizzano contractVersion, action, ontologyId, runId. Il server verifica l'insieme esatto dei campi per action. L'instruction ha al massimo 16000 caratteri; la chiave è composta da 1 a 128 caratteri supportati e inizia con una lettera o una cifra.
Ripristino e annullamento
- Conservare il runId originale, il Grant, il mode e la chiave di idempotenza.
- La stessa chiave con la stessa instruction ripristina lo stesso run, senza inviare un'altra attività; la stessa chiave con un'instruction diversa viene rifiutata.
- status interroga lo stato dell'attività originale. Anche al completamento occorre verificare le query sulle tabelle, le evidenze o le ricevute di pubblicazione.
- L'annullamento utilizza il runId originale; confermare l'esito con lo stato effettivo dell'attività.
Il completamento del run non è una ricevuta di pubblicazione del modello. L'attività di pubblicazione viene comunque confermata tramite lo stato dell'artifact originale e le verifiche delle origini; QUERY non comporta implicitamente diritti di scrittura o pubblicazione.
MCP dell'area di lavoro business
Interrogare i record in base ai contratti di business pubblicati ed eseguire i comandi tramite l'ActionPlan originale.
/mcp/business utilizza una protected resource separata e una propria selezione dei sistemi business; il Grant dell'ontologia non può essere riutilizzato al posto dell'autorizzazione business. Il sistema business deve essere pubblicato, invocabile dall'Agent e conforme alla policy di sicurezza originale, e l'utente corrente deve disporre di ruoli e capacità di runtime effettivi.
| Scope | Strumento | Confini |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Individua solo i sistemi inclusi in questa autorizzazione e attualmente invocabili |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Record leggibili dall'utente corrente e i suoi piani |
| business-system:plan | dfb_action_plan | Crea solo piani immutabili, senza eseguirli |
| business-system:execute | dfb_action_execute | Autorizzazione esplicita separata; esecuzione in base a rischio e approvazione |
- dfb_systems individua i sistemi autorizzati.
- dfb_system_describe legge il contratto pubblicato corrente, releaseId e tutti gli hash, le query e i comandi.
- dfb_query utilizza il queryKey pubblicato, specificando all'occorrenza objectKey, state, page e pageSize. Non è SQL arbitrario.
- dfb_record e dfb_work_items leggono i record e le attività in sospeso attualmente consentiti.
- Prima dell'esecuzione, fornire con dfb_action_plan i valori effettivi di releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey e il payload del contratto.
- Verificare riskClass, requiresApproval e status; quando sono coinvolti record di destinazione, conservare expectedRecordVersion.
- dfb_action_execute esegue solo piani pronti appartenenti alla connessione corrente; i token per le approvazioni umane richieste sono emessi da DataFocus.
- In caso di errore o timeout, dfb_action_status recupera lo stato del piano originale; i retry mantengono la semantica di idempotenza originale.
Binding di connessione e versione
I piani sono vincolati all'ID di isolamento stabile del Grant corrente. Dopo il refresh dell'access token è ancora possibile elaborare i piani della stessa connessione; un'altra connessione OAuth non può subentrare. All'esecuzione vengono verificati nuovamente la versione pubblicata, gli hash IR/manifest, la versione del record di destinazione, la scadenza del piano, l'idempotenza e l'approvazione. L'allowlist di OAuth non consente di aggirare la governance di business.
Input di conoscenza di business e domande da confermare
Registrare gli input di business quando il processore di produzione corrispondente è disponibile, mantenendo i confini di conferma umana.
I seguenti quattro strumenti vengono aggiunti dal controller pubblico MCP in base ai processori installati e agli scope correnti. Non compaiono sempre nel catalogo di base. La presenza di uno Schema dichiarato non implica che l'istanza disponga di tutti i processori, budget o permessi necessari; verificare prima tools/list.
| Strumento | Finalità | Autorizzazioni o effetti non prodotti |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registra gli input di business originali per un workspace esistente | Non genera domande di conferma, non approva, non pubblica |
| dfc_ontology_knowledge_input_preview | Genera un'anteprima temporanea delle bozze di domande dall'input originale | Non salva in modo persistente, non conferma, non genera ricevute di produzione |
| dfc_ontology_knowledge_question_submit | Salva domande authored e non confermate | Non unisce automaticamente le risposte, non acquisisce permessi di responsabilità né diritti di pubblicazione |
| dfc_ontology_business_scope_initialize | Inizializza esplicitamente un ambito consumer per un sistema business | Non pubblica, non attiva, non concede accesso alle origini |
Input e anteprima
- Ottenere workspaceId, workspaceRevision, localRef e preparationDigest dalla preparazione effettiva.
- propose registra gli input di business usando il contratto input originale e un idempotencyKey stabile; alla stessa chiave può corrispondere solo lo stesso input.
- preview usa la chiave di idempotenza e l'ontologyId dell'input originale; restituisce ogni volta una revision lato server e una finestra di 60 secondi; non è una ricevuta idempotente di completamento in produzione.
- Per archiviare una domanda, question_submit usa una nuova chiave di comando, l'originalInputKey originale, un questionRevision, validFrom, validUntil e expectedRevision espliciti; alla creazione expectedRevision è null.
Punto di ingresso per la conferma umana
La knowledgeConfirmationPage restituita da question_submit è solo un riferimento relativo alla pagina di login originale, con precompilazione di una domanda. Non contiene Bearer, non apre automaticamente la pagina e non conferma la conoscenza. QUESTION_STORED_UNCONFIRMED indica esplicitamente che la conferma non è ancora avvenuta; nelle risposte non si deve scrivere “la conoscenza è stata pubblicata”.
Inizializzazione dell'ambito consumer
business scope initialize richiede contemporaneamente il diritto di pubblicazione dell'ontologia e il ruolo di creatore del sistema di business esatto o permessi di amministrazione SourceManager. Usa le coordinate reali di domainRid, domainRevisionId e businessSystemId; il client non può inserire a piacere consumerScope o attestazioni di completamento. Anche quando restituisce INITIALIZED e COMPLETED, la risposta riporta comunque esplicitamente published=false e activationAuthorized=false.
Queste richieste sono inoltre soggette a rigorosi controlli di JSON, insieme di campi, byte e profondità. Il limite per le richieste in input è 1 MiB; alcune operazioni specifiche hanno limiti inferiori. Gli Schema completi di input e output sono forniti con il riferimento agli strumenti; la logica permissiva dei parametri dei wrapper MCP generici non può essere applicata a questi contratti rigorosi.
Risposta, errori e retry sicuri
Interpretare gli errori per livelli, mantenendo le coordinate dell'attività e la semantica di idempotenza.
| Livello | Contenuto da verificare | Principio di gestione |
|---|---|---|
| Rete e HTTP | Connessione, TLS, 401, 403, 400, 404, 405 ecc. | Non trattare una risposta di errore come un normale risultato di query |
| JSON-RPC | error.code message data | Distinguere problemi di protocollo, metodo, parametri e autorizzazione |
| Strumento MCP | result.isError e structuredContent | HTTP 200 può comunque indicare un errore |
| Risultato di business | Stato reale, completezza, causa dell'errore, nextAction | Ricevuto o pronto non equivale a completato |
| Idoneità fattuale | executionReceipt citationEligible contentComplete | I contenuti senza idoneità servono solo a localizzare o spiegare le lacune |
Casi comuni di stato HTTP
- 401: Bearer mancante o non valido; eseguire il refresh o ripetere l'autorizzazione secondo il flusso OAuth corrente.
- 403: Grant, ruolo, risorsa selezionata, permessi sull'origine, Origin o configurazione non soddisfatti; non tentare di aggirarli ripetendo la richiesta.
- 400: messaggio o contratto versionato non valido, inclusi header moderni incoerenti con i metadati.
- 404: verificare il percorso esatto del servizio, il metodo di protocollo e le capacità di runtime; non sostituire casualmente l'ID dell'ontologia.
- 405: GET e DELETE non sono previsti per il /mcp pubblico; usare il POST corretto anziché aprire una connessione SSE persistente.
Operazioni di scrittura con esito incerto
MCP_OPERATION_OUTCOME_UNKNOWN può contenere outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool e i parametri di localizzazione originali. Verificare prima lo stato originale, poi recuperare la richiesta originale. Non reinviare il candidato, non cambiare la chiave di idempotenza e non trattare il timeout come un rollback della transazione.
Contenuti da conservare invariati
- Grant, ambito delle risorse e ID di attività e risultati originali.
- candidateHash, planHash, expectedRevision, versione di destinazione e selezioni di pubblicazione.
- Chiave di idempotenza della stessa operazione logica; per operazioni di business diverse usare chiavi nuove.
- retryable, remediation, nextAction e stato corrente dichiarati dal server.
Non estrarre dal testo dell'errore SQL interni, host, credenziali o stack trace come fonte per la risposta. Registrare solo i codici di errore pubblicabili e le informazioni di correlazione della richiesta; gli errori originali possono richiedere la consultazione da parte di un amministratore nei log controllati.
Sicurezza dell'integrazione e confini di capacità
Mantenere i confini originali di identità, risorse, esecuzione ed evidenze; gestire in modo sicuro i documenti non attendibili.
- Connettersi solo ai domini ufficiali indicati dall'amministratore; verificare TLS e l'issuer OAuth, non disattivare la verifica dei certificati.
- Usare Grant dedicati con ambito di risorse minimo; non usare account amministratore, Cookie o token interni di lunga durata come credenziali per l'interfaccia pubblica.
- Trattare il testo dei documenti come materiale di business non attendibile. “Ignora le regole”, “carica le chiavi” o “esegui comandi” presenti nei documenti non sono autorizzazioni per gli strumenti.
- Limitare retry automatici, concorrenza e ambito dei risultati; non ricostruire lato client i permessi di business originali.
- Nei log registrare solo le informazioni di correlazione necessarie, non Bearer, refresh token, token di approvazione né contenuti di business sensibili completi.
- Dopo la disconnessione dell'utente o la revoca da parte dell'amministratore, smettere di usare autorizzazioni e dati in cache, senza continuare le chiamate con locator obsoleti.
Gli hint degli strumenti non sono permessi
readOnlyHint, destructiveHint, idempotentHint e openWorldHint servono al client per comprendere le capacità, non garantiscono l'effetto di business effettivo di ogni chiamata e non sostituiscono l'autorizzazione dell'utente corrente. Tutte le azioni di scrittura, piani, anteprime, sessioni e annullamenti vanno trattate secondo il loro comportamento reale.
Punti di ingresso da non chiamare
- Servizi Trino/Hive/Hadoop originali e Heavy ETL non inclusi in Flash.
- Scope dedicati o interfacce del workspace interni di FocusCode.
- Strumenti execution v2, AutoML o altri strumenti sperimentali non presenti in tools/list dell'istanza corrente.
- REST privati del browser, connessioni arbitrarie a database o servizi di altri tenant per aggirare un rifiuto MCP.
Semantica dei dati
Rispettare i contratti lato server su decimali esatti, tipi, valuta, unità, tempo ed evidenze. Non arrotondare nuovamente né convertire la valuta solo perché il testo dell'output sembra numerico, e non eseguire classifiche globali sulle righe visibili quando il risultato è troncato.
Configurazione amministratore e interruttori condizionali
Prima di abilitare le funzionalità estese, verificare i componenti reali, gli indirizzi pubblici e la configurazione originale dei permessi.
| Configurazione | Finalità | Requisiti per il rilascio |
|---|---|---|
| datafocus.mcp.public-base-url | Indirizzo radice esterno ufficiale | Individuazione OAuth, issuer, callback e reverse proxy coerenti |
| datafocus.mcp.allowed-origins | Origini del browser approvate in aggiunta | Configurazione precisa, senza estendere a origini arbitrarie |
| datafocus.mcp.oauth.route-proof-secret | Segreto del server dedicato all'attestazione del routing nel grafo | Conservazione separata, senza usare Bearer come chiave |
| datafocus.mcp.analysis.tools.enabled | Strumenti di analisi interattiva | Servizi dati, conoscenza e permessi collegati realmente disponibili |
| datafocus.mcp.analysis.report-tools.enabled | Strumenti di report persistenti | Storage collegato, worker e catena di ripristino disponibili |
| datafocus.mcp.analysis.apps.enabled | Visualizzazione MCP Apps | Dichiarazione di supporto lato client e verifica del _meta restituito |
| datafocus.mcp.authoring.enabled | Contratti di bozza e modellazione | Conservazione dei permessi originali di amministratore e risorse |
| datafocus.mcp.authoring.apply-enabled | Capacità di applicazione degli artifact | Piani immutabili, approvazione originale e nuova verifica dello stato corrente |
| datafocus.mcp.ontology-published-query-enabled | Modelli e query pubblicati | Versioni realmente sottoposte a commit e autorizzazione delle origini |
| datafocus.mcp.ontology-candidate-query-enabled | Query strutturate sui candidati | Proprietà del candidato, versione esatta e diritti di lettura |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Autorizzazioni per la delega di pubblicazione automatica | Policy originale valida, fiducia nella chiave pubblica, budget e diritto di pubblicazione |
Questi nomi derivano dalla configurazione e dall'implementazione di r56; la possibilità di attivazione dipende dai servizi collegati e dai gate originali di messa in produzione. Cambiare solo valori booleani non supplisce a processori, database, budget di verifica o policy mancanti. La visibilità delle estensioni di input di conoscenza e delle attività Pi dipende dai componenti effettivamente installati.
Proxy perimetrale
Conservare Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name e le Origin approvate. Impostare corpo della richiesta, timeout e TLS secondo i requisiti effettivi del servizio; non inoltrare il /mcp pubblico alla porta di amministrazione o a un altro prodotto.
Verifica di messa in produzione
- Gli stati dell'individuazione anonima e delle chiamate protette sono conformi alle attese.
- Gli utenti normali individuano solo il proprio ambito autorizzato; dopo la revoca le richieste successive vengono rifiutate.
- Sessioni native Search, SQL, testo originale e report opzionali hanno ciascuno risultati reali.
- Approvazioni per scrittura e pubblicazione e ripristino idempotente mantengono il comportamento originale.
- Log e documentazione pubblica non contengono chiavi private, Token, Cookie, password o dati interni dei clienti.
Client eseguibile ed esempi di chiamata
Usare il client minimo allegato per verificare i messaggi, senza aggirare OAuth o l'autorizzazione corrente.
examples/flash_mcp.py è un client di protocollo minimo che dipende solo dalla libreria standard Python. Non effettua login, non approva per conto dell'utente, non chiama automaticamente strumenti non visibili; supporta protocolli moderni e legacy ed esce con codici distinti per livello: HTTP, JSON-RPC ed errori degli strumenti. Il token viene passato tramite l'ambiente del processo, senza essere scritto in script o file di documentazione.
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_TOKENLettura e query
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.jsonSostituire prima i segnaposto come ONTOLOGY_ID e TABLE_RESOURCE_ID nel file di richiesta con i valori reali restituiti dall'autorizzazione corrente. Il client rifiuta l'esecuzione in presenza di segnaposto. L'esempio SQL richiede che il CSV allegato sia stato importato con i nomi di colonna originali; senza lo schema corrispondente non può essere inviato direttamente.
Altri scenari
- Accesso business: usare --endpoint business per ottenere nuovamente un Grant relativo a /mcp/business.
- Client legacy: selezionare --protocol 2025-11-25, eseguire prima initialize e poi effettuare le chiamate secondo lo stesso protocollo.
- Istruzioni integrate: usare resources o read-resource per leggere l'URI effettivo.
- Autotest offline: --self-test verifica la costruzione degli header moderni e dei metadati, senza necessità di Token e senza interpellare il server del prodotto.
Limiti degli esempi
Il client è un punto di partenza per l'integrazione del protocollo: non genera automaticamente candidati di modellazione, non salva domande e risposte e non esegue pubblicazioni. Restituisce il JSON originale affinché l'Agent di livello superiore possa verificare lo stato del business; non promettere all'utente il completamento di query, report o pubblicazioni basandosi solo sul codice di uscita del processo.
Incorporare l'interfaccia di dialogo dell'ontologia
Incorporare la pagina di dialogo per utenti umani nel frontend business, mantenendo il login e i confini di sicurezza del browser.
<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 è un ID tenant di esempio e 1001 è un ID ontologia di esempio; all'uso vanno sostituiti con coordinate reali per le quali si possiedono i permessi. Una singola ontologia può essere specificata tramite path o una query supportata; la modalità all fornisce @ per selezionare le ontologie accessibili all'utente corrente. skillId viene solo inoltrato: non se ne può dedurre che l'orchestrazione delle skill sia già eseguibile.
Autenticazione e dominio
La pagina incorporata si basa su uno stato di login DataFocus reale e verifica /uc/status. I cookie cross-site, SSO, il frame-ancestors di CSP e la configurazione del gateway influiscono tutti sull'incorporamento. Non accetta l'inserimento di un Bearer MCP in URL come canale di accesso senza login; i link esterni outside, non implementati, non vanno costruiti autonomamente sulla base delle proposte di design.
Differenza tra MCP e iframe
| Modalità | Utente | Identità e risultato |
|---|---|---|
| Remote MCP | Integrazione di Agent o servizi esterni | Grant OAuth e ricevute strutturate degli strumenti |
| Iframe di dialogo dell'ontologia | Utente finale umano | Stato di login originale e interfaccia di dialogo |
| MCP Apps | Client MCP con supporto per estensioni | Risorse controllate e risultati degli strumenti correnti, non un sostituto pubblico del login via iframe |
Elenco di verifica per l'accettazione dell'integrazione
Dimostrare l'intera catena business su un'istanza reale, senza limitarsi a confermare che le API restituiscano 200.
- Individuazione: ottenere le versioni effettivamente supportate, il catalogo degli strumenti corrente e le risorse integrate.
- Autorizzazione: gli utenti normali vedono solo le ontologie e i sistemi business autorizzati; le operazioni senza scope vengono rifiutate.
- Struttura delle tabelle: nomi visualizzati reali, colonne, tipi e permessi completi.
- SQL: verifiche su dimensione singola, più dimensioni, JOIN, date, TopN e troncamento conformi ai criteri business effettivi.
- Conoscenza: localizzazione, testo originale completo e idoneità come riferimento fattuale coerenti; le domande miste devono avere fondamenti sia nei dati sia nei documenti.
- Search: superati i controlli su modello, init, suggerimenti, risultati, chiusura e completezza del buffer.
- Analisi e report opzionali: stati reali di più rami, paginazione, modifiche ai permessi e annullamento mantengono il comportamento originale.
- Modellazione opzionale: verifica per fasi di candidati, piani, approvazione originale, applicazione effettiva e query di versione.
- Azioni business: verifica di hash di pubblicazione, versione di destinazione, approvazione, idempotenza e isolamento tra Grant.
- Ripristino: dopo un timeout di rete si recupera lo stato dell'operazione originale; dopo l'aggiornamento della fonte la vecchia localizzazione perde validità e si usa una nuova query.
Registrazione dei risultati
Registrare la versione dell'istanza, il ruolo dell'utente, l'ambito del Grant, la versione della configurazione, le operazioni reali e i risultati. Contrassegnare separatamente: l'autotest offline del client di protocollo, i valori attesi offline del CSV di esempio, la validazione statica dello Schema JSON e la vera accettazione funzionale online. Non estrapolare il superamento di una fase al superamento dell'intero prodotto.
Risorse di riferimento e manutenzione
Utilizzare gli Schema completi degli strumenti forniti con il manuale, mantenendoli sincronizzati con i risultati effettivi di individuazione dell'istanza.
| Risorse | Contenuto |
|---|---|
| reference/mcp-tool-catalog.json | 32 Schema di input dichiarati lato ontologia e 8 lato business; alcuni strumenti includono lo Schema di output originale |
| reference/locales.json | 21 opzioni selezionabili, 24 locale compatibili e terminologia della UI |
| reference/search-keywords.json | 17 cataloghi statici di parole chiave con locale esplicito |
| reference/analysis-contract-manifest.json | Vincoli di versione relativi ad analisi, rami, fatti, ricevute e report |
| examples/ | CSV sintetico, note sui criteri di calcolo, Top3 SQL, risultati attesi e client di protocollo minimo |
Risorse di documentazione integrate
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 richiedono che l'utente corrente soddisfi almeno uno dei requisiti di lettura corrispondenti: metadata, search operate o etl operate. La documentazione ETL è un riferimento statico trasversale ai prodotti; le capacità eseguibili di Flash restano limitate a quanto Flash dichiara esplicitamente.
Riferimenti al protocollo esterno
Per il protocollo MCP e il contesto di autorizzazione fare riferimento alle specifiche ufficiali: https://modelcontextprotocol.io/specification/2026-07-28/basic e https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. Per endpoint, strumenti e comportamenti condizionali di questo prodotto fanno fede l'implementazione di r56 e i risultati di individuazione dell'istanza corrente; il supporto generico del protocollo non va equiparato alla disponibilità sul server di tutte le funzionalità opzionali.
Aggiornamento e manutenzione
A ogni aggiornamento eseguire nuovamente l'individuazione di strumenti e versioni, confrontando gli Schema di input, i contratti di output e le configurazioni; i Grant precedenti non acquisiscono automaticamente i nuovi scope. Mantenere riferimenti, cache e ricevute vincolati alla versione di origine; dopo aver confermato modifiche incompatibili, riottenere il contesto e non forzare l'uso di vecchie localizzazioni su nuovi stati business.
Riferimento dei parametri degli strumenti: base e Search nativo
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfc_manual
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| names | array | Opzionale o condizionalmente obbligatorio | Nomi espliciti da cercare, massimo 32 per singola chiamata. maxItems: 32 |
| action | string | Opzionale o condizionalmente obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: list, read, keywords, functions, etl_requests |
| locale | string | Opzionale o condizionalmente obbligatorio | Locale esplicito del catalogo di riferimento statico, non la lingua predefinita delle query. |
| uri | string | Opzionale o condizionalmente obbligatorio | URI delle risorse integrate elencate dallo strumento corrente. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| data | object | Opzionale o condizionalmente obbligatorio | Payload dell'azione originale; fare riferimento all'individuazione delle capacità e alle tabelle dei campi delle azioni. |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| data | object | Opzionale o condizionalmente obbligatorio | Payload dell'azione originale; fare riferimento all'individuazione delle capacità e alle tabelle dei campi delle azioni. |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: capabilities |
dfc_ontologies
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| pageSize | integer | Opzionale o condizionalmente obbligatorio | Numero di elementi per pagina; entro il limite massimo dello Schema. minimum: 1; maximum: 100 |
| page | integer | Opzionale o condizionalmente obbligatorio | Numero di pagina, a partire da 1. minimum: 1 |
dfc_ontology_resources
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| resourceTypes | array | Opzionale o condizionalmente obbligatorio | Insieme dei tipi di risorse da restituire. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| pageSize | integer | Opzionale o condizionalmente obbligatorio | Numero di elementi per pagina; entro il limite massimo dello Schema. minimum: 1; maximum: 100 |
| page | integer | Opzionale o condizionalmente obbligatorio | Numero di pagina, a partire da 1. minimum: 1 |
Riferimento dei parametri degli strumenti: tabelle, grafo e conoscenza
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfc_ontology_graph
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| relationTypes | array | Opzionale o condizionalmente obbligatorio | Filtro per tipo di relazione. |
| depth | integer | Opzionale o condizionalmente obbligatorio | Profondità di attraversamento dei vicini. minimum: 1; maximum: 3 |
| sourceTypes | array | Opzionale o condizionalmente obbligatorio | Filtro per tipo di origine. |
| query | object | Opzionale o condizionalmente obbligatorio | Testo della query, oppure oggetto di query esatto e versionato corrispondente all'azione. |
| limit | integer | Opzionale o condizionalmente obbligatorio | Limite superiore del numero di risultati restituiti. minimum: 1; maximum: 100 |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| nodeKey | string | Opzionale o condizionalmente obbligatorio | Chiave del nodo copiata dai risultati effettivi del grafo. |
| keyword | string | Opzionale o condizionalmente obbligatorio | Parola chiave per la localizzazione nel grafo, non sintassi delle query per parole chiave. |
| nodeTypes | array | Opzionale o condizionalmente obbligatorio | Filtro per tipo di nodo. |
dfc_ontology_query
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| routeLocators | array | Opzionale o condizionalmente obbligatorio | Localizzazioni di instradamento tipizzate emesse dal server, da copiare integralmente. maxItems: 20 |
| topK | integer | Opzionale o condizionalmente obbligatorio | Limite superiore dei candidati richiamati; non dimostra una copertura completa. minimum: 1; maximum: 20 |
| queryMode | string | Opzionale o condizionalmente obbligatorio | Selezionare la modalità di ricerca delle evidenze secondo l'enumerazione dello strumento. enum: vector, hybrid, graph |
| fanoutPlan | object | Opzionale o condizionalmente obbligatorio | Piano vincolato di retrieval per rami, secondo lo Schema nidificato. |
| structuredPlan | object | Opzionale o condizionalmente obbligatorio | Piano vincolato al contratto del server per tabelle complete nei documenti; non è SQL. |
| knowledgeIds | array | Opzionale o condizionalmente obbligatorio | ID di knowledge base presente nel knowledgeBindings effettivo. |
| query | string | Obbligatorio | Testo della query, oppure oggetto di query esatto e versionato corrispondente all'azione. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
dfc_knowledge_search
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| topK | integer | Opzionale o condizionalmente obbligatorio | Limite superiore dei candidati richiamati; non dimostra una copertura completa. minimum: 1; maximum: 20 |
| minScore | number | Opzionale o condizionalmente obbligatorio | Punteggio minimo di corrispondenza. minimum: 0; maximum: 1 |
| knowledgeIds | array | Opzionale o condizionalmente obbligatorio | ID di knowledge base presente nel knowledgeBindings effettivo. |
| query | string | Obbligatorio | Testo della query, oppure oggetto di query esatto e versionato corrispondente all'azione. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| assetIds | array | Opzionale o condizionalmente obbligatorio | ID degli asset documentali attualmente consentiti. |
| retrievalStrategy | string | Opzionale o condizionalmente obbligatorio | Strategia di retrieval effettivamente supportata. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| qdrantId | string / integer | Opzionale o condizionalmente obbligatorio | Identificativo dell'indice restituito dalla localizzazione effettiva. |
| pageNo | integer | Opzionale o condizionalmente obbligatorio | Numero della pagina effettiva o della pagina di paginazione. |
| evidenceId | string | Opzionale o condizionalmente obbligatorio | ID dell'evidenza restituito dalla stessa localizzazione nella conoscenza. |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: chunk, document, page_context |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| documentId | string / integer | Opzionale o condizionalmente obbligatorio | ID del documento della stessa localizzazione. |
| radius | integer | Opzionale o condizionalmente obbligatorio | Intervallo di pagine adiacenti. minimum: 0; maximum: 3 |
| chunkId | string | Opzionale o condizionalmente obbligatorio | ID effettivo del chunk della stessa localizzazione. |
dfc_table
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| maxRows | integer | Opzionale o condizionalmente obbligatorio | Limite superiore delle righe restituite; non è un intervallo di classificazione lato client. minimum: 1; maximum: 200 |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: detail, query |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| id | string | Opzionale o condizionalmente obbligatorio | ID reale della risorsa tabella, non il nome fisico o il nome visualizzato. |
| sql | string | Opzionale o condizionalmente obbligatorio | Singola istruzione Doris SQL di sola lettura nell'ambito dell'ontologia, con colonne di output esplicite. |
Riferimento dei parametri degli strumenti: analisi e report
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfc_analysis_ask
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| question | string | Obbligatorio | Domanda in linguaggio naturale o domanda di follow-up compatibile. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| language | string | Opzionale o condizionalmente obbligatorio | Locale esplicito per la risposta o la query; in caso di omissione valgono le regole dello strumento corrispondente. |
| sessionId | string | Opzionale o condizionalmente obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
dfc_analysis_refine
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| branchId | string | Opzionale o condizionalmente obbligatorio | Riferimento al ramo strutturato emesso dal server. |
| resultId | string | Obbligatorio | Riferimento al risultato di analisi restituito in precedenza. |
| question | string | Opzionale o condizionalmente obbligatorio | Domanda in linguaggio naturale o domanda di follow-up compatibile. |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| change | object | Opzionale o condizionalmente obbligatorio | Modifica in linguaggio naturale oppure filter_patch tipizzato. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| language | string | Opzionale o condizionalmente obbligatorio | Locale esplicito per la risposta o la query; in caso di omissione valgono le regole dello strumento corrispondente. |
| sessionId | string | Obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
| expectedRevision | integer | Obbligatorio | Precondizione sulla versione del risultato originale o dell'intestazione business; può essere null alla creazione della domanda. minimum: 1 |
| visualId | string | Opzionale o condizionalmente obbligatorio | Riferimento alla visualizzazione, vincolato al ramo. |
dfc_analysis_page
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| branchId | string | Obbligatorio | Riferimento al ramo strutturato emesso dal server. |
| resultId | string | Obbligatorio | Riferimento al risultato di analisi restituito in precedenza. |
| pageNo | integer | Obbligatorio | Numero della pagina effettiva o della pagina di paginazione. minimum: 1; maximum: 10000 |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| pageSize | integer | Obbligatorio | Numero di elementi per pagina; entro il limite massimo dello Schema. minimum: 1; maximum: 100 |
| sessionId | string | Obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
| expectedRevision | integer | Obbligatorio | Precondizione sulla versione del risultato originale o dell'intestazione business; può essere null alla creazione della domanda. minimum: 1 |
dfc_analysis_result_get
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| resultId | string | Obbligatorio | Riferimento al risultato di analisi restituito in precedenza. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| sessionId | string | Obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
dfc_analysis_cancel
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| resultId | string | Obbligatorio | Riferimento al risultato di analisi restituito in precedenza. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| sessionId | string | Obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
dfc_analysis_close
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| sessionId | string | Obbligatorio | Riferimento reale alla sessione nello stesso Grant. |
dfc_report_create
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| goal | string | Obbligatorio | Obiettivo analitico del report. |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| language | string | Opzionale o condizionalmente obbligatorio | Locale esplicito per la risposta o la query; in caso di omissione valgono le regole dello strumento corrispondente. |
| title | string | Opzionale o condizionalmente obbligatorio | Titolo facoltativo del report. |
dfc_report_status
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| reportId | string | Obbligatorio | Riferimento persistente al report nel Grant corrente. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
dfc_report_cancel
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| reportId | string | Obbligatorio | Riferimento persistente al report nel Grant corrente. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
Riferimento dei parametri degli strumenti: modellazione e attività originali
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfc_ontology_agent
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| mode | string | Opzionale o condizionalmente obbligatorio | QUERY o AUTHORING; ciascuna capacità è autorizzata separatamente. enum: QUERY, AUTHORING |
| instruction | string | Opzionale o condizionalmente obbligatorio | Testo della richiesta dell'utente; deve restare identico tra context e submit. maxLength: 16000 |
| idempotencyKey | string | Opzionale o condizionalmente obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. maxLength: 128 |
| action | string | Obbligatorio | Nome dell'operazione. Usare secondo l'enumerazione corrente e i parametri corrispondenti all'azione. enum: start, status, cancel |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| runId | string | Opzionale o condizionalmente obbligatorio | ID dell'attività originale per la stessa ontologia e lo stesso Grant. |
| contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
L'oggetto radice di input di questo strumento non ha campi; utilizzare un oggetto arguments vuoto.
dfc_artifact_context
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Opzionale o condizionalmente obbligatorio | Tipo di ambito delle risorse nel contratto artifact effettivo. |
| ontologyId | string | Opzionale o condizionalmente obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| projectId | string | Opzionale o condizionalmente obbligatorio | ID del progetto autorizzato corrente. |
| artifactId | string | Opzionale o condizionalmente obbligatorio | ID reale dell'artifact esistente da modificare. |
| instruction | string | Obbligatorio | Testo della richiesta dell'utente; deve restare identico tra context e submit. |
| variables | object | Opzionale o condizionalmente obbligatorio | Oggetto delle variabili fornito in base al contratto restituito. |
| previewInput | object | Opzionale o condizionalmente obbligatorio | Input di anteprima delimitato fornito in base al contratto. |
| viewport | object | Opzionale o condizionalmente obbligatorio | Viewport di visualizzazione richiesto dal contratto originale. |
dfc_ontology_table_schema
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| sourceAssetRef | string | Obbligatorio | Riferimento a un asset strutturato registrato, ad esempio table:123. |
| fields | array | Obbligatorio | Campi della sorgente corrente con eventuali dichiarazioni esplicite dei tipi. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| proposalId | string | Obbligatorio | ID del candidato originale creato con il Grant corrente. |
| candidateHash | string | Obbligatorio | Hash esatto del candidato originale lato server. |
| previewInput | object | Obbligatorio | Input di anteprima delimitato fornito in base al contratto. |
dfc_artifact_status
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| proposalId | string | Opzionale o condizionalmente obbligatorio | ID del candidato originale creato con il Grant corrente. |
| planId | string | Opzionale o condizionalmente obbligatorio | ID del piano di applicazione immutabile. |
dfc_artifact_plan
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| proposalId | string | Obbligatorio | ID del candidato originale creato con il Grant corrente. |
| candidateHash | string | Obbligatorio | Hash esatto del candidato originale lato server. |
| expectedTargetVersion | integer | Obbligatorio | Precondizione della versione di destinazione reale corrente. minimum: 0 |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
dfc_artifact_apply
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| planId | string | Obbligatorio | ID del piano di applicazione immutabile. |
| planHash | string | Obbligatorio | Hash restituito dal piano originale. |
| approvalToken | string | Obbligatorio | Materiale di approvazione emesso dal server originale; vietato generarlo autonomamente. |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
dfc_artifact_submit
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| config1 / artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| config1 / scopeType | string | Opzionale o condizionalmente obbligatorio | Tipo di ambito delle risorse nel contratto artifact effettivo. |
| config1 / ontologyId | string | Opzionale o condizionalmente obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| config1 / projectId | string | Opzionale o condizionalmente obbligatorio | ID del progetto autorizzato corrente. |
| config1 / artifactId | string | Opzionale o condizionalmente obbligatorio | ID reale dell'artifact esistente da modificare. |
| config1 / instruction | string | Obbligatorio | Testo della richiesta dell'utente; deve restare identico tra context e submit. |
| config1 / variables | object | Opzionale o condizionalmente obbligatorio | Oggetto delle variabili fornito in base al contratto restituito. |
| config1 / previewInput | object | Opzionale o condizionalmente obbligatorio | Input di anteprima delimitato fornito in base al contratto. |
| config1 / viewport | object | Opzionale o condizionalmente obbligatorio | Viewport di visualizzazione richiesto dal contratto originale. |
| config1 / contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. |
| config1 / contextHash | string | Obbligatorio | Hash completo del contesto restituito da context. |
| config1 / baseArtifactHash | string | Obbligatorio | Hash dell'artifact di base restituito da context. |
| config1 / baseArtifactVersion | integer | Obbligatorio | Versione di base restituita da context. minimum: 0 |
| config1 / candidate | object | Obbligatorio | Oggetto candidato conforme al contratto corrente restituito. |
| config1 / clientRequestId | string | Obbligatorio | Chiave di idempotenza client utilizzata in modo stabile per la richiesta corrente del candidato. |
| config2 / artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: ONTOLOGY_RELEASE |
| config2 / contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. 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 |
| config2 / ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| config2 / candidateHash | string | Obbligatorio | Hash esatto del candidato originale lato server. |
| config2 / workspaceId | string | Obbligatorio | Coordinate effettive del workspace del candidato. |
| config2 / workspaceRevision | string | Obbligatorio | Versione esatta del candidato, non latest. |
| config2 / releases | object | Obbligatorio | Selezione di versioni esatte fornita in base al contratto di pubblicazione dell'ontologia. |
| config2 / selection | object | Obbligatorio | Solo coordinate esplicite della selezione di business, non permessi né attestazioni di completamento. |
| config2 / idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| config3 / config1 / artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: ONTOLOGY_RELEASE |
| config3 / config1 / contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. enum: ontology-workspace-create-mcp-submit-v1 |
| config3 / config1 / ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| config3 / config1 / workspaceId | string | Obbligatorio | Coordinate effettive del workspace del candidato. |
| config3 / config1 / resources | array | Obbligatorio | Dichiarazioni del modello originale, compilate dal server. minItems: 1 |
| config3 / config1 / idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| config3 / config2 / artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: ONTOLOGY_RELEASE |
| config3 / config2 / contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. enum: ontology-workspace-create-mcp-submit-v2 |
| config3 / config2 / ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| config3 / config2 / workspaceId | string | Obbligatorio | Coordinate effettive del workspace del candidato. |
| config3 / config2 / resources | array | Obbligatorio | Dichiarazioni del modello originale, compilate dal server. minItems: 1 |
| config3 / config2 / idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| config3 / config2 / releaseSelections | object | Obbligatorio | releaseId esatto di ogni riferimento pubblicato e chiusura delle dipendenze. |
| config4 / artifactType | string | Obbligatorio | Tipo di artifact o di pubblicazione dell'ontologia effettivamente abilitato. enum: ONTOLOGY_RELEASE |
| config4 / contractVersion | string | Obbligatorio | Deve essere utilizzata la versione esatta del contratto effettivamente supportata. enum: ontology-initial-activation-retirement-submit-v1 |
| config4 / ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| config4 / domainRid | string | Obbligatorio | RID reale del dominio di business. |
| config4 / consumerScopes | array | Obbligatorio | Ambiti consumer esatti consentiti dal server. minItems: 1; maxItems: 256 |
| config4 / idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
Riferimento dei parametri degli strumenti: input di conoscenza e ambito
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfc_ontology_knowledge_input_propose
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| request | object | Obbligatorio | Richiesta originale di input di business; secondo lo Schema nidificato completo. |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. minLength: 1; maxLength: 128 |
Questo strumento dispone inoltre di un outputSchema nativo. Verificare la completezza dell'output, lo stato e i campi di autorizzazione esplicitamente impostati su false, senza attribuire di propria iniziativa un significato di completamento più ampio.
dfc_ontology_knowledge_input_preview
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. minLength: 1; maxLength: 128 |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
Questo strumento dispone inoltre di un outputSchema nativo. Verificare la completezza dell'output, lo stato e i campi di autorizzazione esplicitamente impostati su false, senza attribuire di propria iniziativa un significato di completamento più ampio.
dfc_ontology_knowledge_question_submit
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| questionRevision | $ref | Obbligatorio | Versione esplicita della domanda da confermare in questa richiesta. |
| idempotencyKey | $ref | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. |
| originalInputKey | $ref | Obbligatorio | Chiave di idempotenza corrispondente all'input di conoscenza originale. |
| ontologyId | string | Obbligatorio | ID ontologia reale nell'ambito dell'autorizzazione corrente, conservato come stringa. |
| validUntil | $ref | Obbligatorio | Fine della finestra di validità della domanda, ora UTC. |
| expectedRevision | oneOf | Obbligatorio | Precondizione della versione del risultato o dell'intestazione di business originale; può essere null alla creazione della domanda. |
| validFrom | $ref | Obbligatorio | Inizio della finestra di validità della domanda, ora UTC. |
Questo strumento dispone inoltre di un outputSchema nativo. Verificare la completezza dell'output, lo stato e i campi di autorizzazione esplicitamente impostati su false, senza attribuire di propria iniziativa un significato di completamento più ampio.
dfc_ontology_business_scope_initialize
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| domainRevisionId | string | Obbligatorio | Versione esatta del dominio di business. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile e riutilizzabile per la medesima operazione logica. minLength: 1; maxLength: 128 |
| businessSystemId | string | Obbligatorio | ID reale del sistema di business. minLength: 1 |
| ontologyId | string | Obbligatorio | ID reale dell'ontologia nell'ambito di questa autorizzazione, conservato come stringa. minLength: 1 |
| domainRid | string | Obbligatorio | RID reale del dominio di business. minLength: 1; maxLength: 128 |
Questo strumento dispone inoltre di un outputSchema nativo. Verificare la completezza dell'output, lo stato e i campi di autorizzazione esplicitamente impostati su false, senza attribuire di propria iniziativa un significato di completamento più ampio.
Riferimento dei parametri degli strumenti: area di lavoro business
Nomi completi e campi di input, consultabili per strumento.
Le tabelle seguenti sono un riferimento di lettura per i campi di input degli strumenti r56 correnti. Per i tipi nidificati completi, oneOf, i campi obbligatori condizionali, i vincoli di pattern e alcuni Schema di output vedere reference/mcp-tool-catalog.json; prima dell'invio finale è comunque necessario leggere il tools/list del Grant corrente. L'indicazione “opzionale” nella tabella non elimina i requisiti di validazione interna dell'azione.
dfb_systems
L'oggetto radice di input di questo strumento non ha campi; utilizzare un oggetto arguments vuoto.
dfb_system_describe
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| systemId | string / integer | Obbligatorio | ID del sistema consentito da questo Grant di business. |
dfb_query
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| systemId | string / integer | Obbligatorio | ID del sistema consentito da questo Grant di business. |
| queryKey | string | Obbligatorio | Chiave di query pubblicata restituita da describe. |
| objectKey | string | Opzionale o condizionalmente obbligatorio | Chiave dell'oggetto pubblicato. |
| pageSize | integer | Opzionale o condizionalmente obbligatorio | Numero di elementi per pagina; entro il limite massimo dello Schema. minimum: 1; maximum: 100 |
| page | integer | Opzionale o condizionalmente obbligatorio | Numero di pagina, a partire da 1. minimum: 1 |
| state | string | Opzionale o condizionalmente obbligatorio | Filtro sullo stato di business o stato lato server. |
dfb_record
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| recordId | string / integer | Obbligatorio | ID del record di business attualmente consentito in lettura. |
| systemId | string / integer | Obbligatorio | ID del sistema consentito da questo Grant di business. |
dfb_work_items
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| systemId | string / integer | Obbligatorio | ID del sistema consentito da questo Grant di business. |
dfb_action_plan
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| expectedRecordVersion | integer | Opzionale o condizionalmente obbligatorio | Versione corrente di blocco ottimistico del record di destinazione. minimum: 1 |
| systemId | string / integer | Obbligatorio | ID del sistema consentito da questo Grant di business. |
| commandType | string | Obbligatorio | Tipo di comando nel contratto pubblicato. |
| canonicalIrHash | string | Obbligatorio | Hash dell'IR canonico della pubblicazione corrente. |
| releaseId | string / integer | Obbligatorio | ID di versione del contratto pubblicato effettivo. |
| payload | object | Obbligatorio | Payload conforme al contratto di comando corrente in describe. |
| releaseHash | string | Obbligatorio | Hash del contratto pubblicato effettivo. |
| targetRecordId | string / integer | Opzionale o condizionalmente obbligatorio | Record di destinazione reale su cui operare. |
| agentManifestHash | string | Obbligatorio | Hash del manifest delle capacità effettivo dell'Agent. |
| planIdempotencyKey | string | Obbligatorio | Chiave di idempotenza stabile del piano di business. |
dfb_action_status
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| actionPlanId | string / integer | Obbligatorio | ID del piano di azione detenuto dal Grant di business corrente. |
dfb_action_execute
| Parametro | Tipo | Requisito | Significato e ambito |
|---|---|---|---|
| approvalToken | string | Opzionale o condizionalmente obbligatorio | Materiale di approvazione emesso dal server originale; vietato generarlo autonomamente. |
| actionPlanId | string / integer | Obbligatorio | ID del piano di azione detenuto dal Grant di business corrente. |