OT Flash Agent- og MCP-integrasjonshåndbok
Protokoll, autorisering, verktøykontrakter og komplett kallflyt
Bygg sporbare data- og kunnskapsapplikasjoner med den offentlige Remote MCP-en i OT Flash r56. Denne håndboken dekker OAuth, protokollmeldinger, parameterreferanse for alle deklarerte verktøy, bevisregler, betingede funksjoner og gjenopprettingsflyter, og inneholder en kjørbar klient og eksempler med syntetiske data.
Agentutviklere, integrasjonsingeniører og administratorer
De medfølgende eksemplene beholder de kinesiske visningsnavnene på feltene. Oversettelse av grensesnittspråket og den forklarende teksten endrer ikke faktiske tabellnavn, kolonnenavn, enum-verdier, verktøynavn eller protokollfelt.
Innhold
- 1Agentens integrasjonsomfang og fullføringskriterier
- 2Rask tilkobling og funksjonsoppdagelse
- 3OAuth-oppdagelse, registrering og autorisering
- 4Scope, ressursgrenser og sanntidsrettigheter
- 5HTTP og moderne MCP-meldinger
- 6Kompatibilitet med eldre protokollklienter
- 7Velg riktig verktøy og beviskanal
- 8Ontologiressurser og ID-typer
- 9Doris-tabellspørrings- og strukturkontrakt
- 10Flerdimensjonal topp 3 og håndtering av trunkering
- 11Kunnskapssøk: fullstendig originaltekst og kvalifisering som bevis
- 12Innebygde Search-modeller og økter
- 13Språk- og regionkonvensjoner
- 14Fusjonsanalyse og interaktive resultater
- 15Vedvarende visualiseringsrapporter og MCP Apps
- 16Artefaktkladd, forhåndsvisning, plan og anvendelse
- 17Oppretting av ontologikandidater og publiseringskontrakter
- 18Publisert modell, kandidatspørring og referanselukking
- 19Delegerte oppgaver for ontologiagenten
- 20Business Workspace MCP
- 21Inndata for forretningskunnskap og spørsmål som venter på bekreftelse
- 22Svar, feil og sikre nye forsøk
- 23Integrasjonssikkerhet og funksjonsgrenser
- 24Administratoroppsett og betingede brytere
- 25Kjørbare klienter og eksempelkall
- 26Bygg inn ontologidialoggrensesnittet
- 27Sjekkliste for integrasjonsgodkjenning
- 28Spesifikasjonsressurser og vedlikehold
- 29Verktøyparameterreferanse: grunnleggende og innebygd Search
- 30Verktøyparameterreferanse: tabeller, graf og kunnskap
- 31Verktøyparameterreferanse: analyse og rapporter
- 32Verktøyparameterreferanse: modellering og opprinnelige oppgaver
- 33Verktøyparameterreferanse: kunnskapsinndata og omfang
- 34Verktøyparameterreferanse: Business Workspace
Agentens integrasjonsomfang og fullføringskriterier
Velg riktig inngang for autorisering, og fullfør spørring, bevisinnhenting eller kontrollert skriving ut fra kvitteringen fra serveren.
OT Flash r56 gir eksterne agenter data- og kunnskapsfunksjoner innenfor ontologiområdet via Remote MCP, og tilbyr en egen inngang til Business Workspace. Agenten skal avgjøre hvilket arbeid som kan utføres, ut fra faktisk tools/list, inputSchema, OAuth scope og gjeldende ressursrettigheter, og kan ikke ut fra en statisk håndbok anta at en distribusjon har alle valgfrie funksjoner aktivert.
| Inngang | Formål | Grenser |
|---|---|---|
| /mcp | Ontologi, datatabeller, dokumentkunnskap, innebygd Search samt betinget tilgjengelige analyse- og modelleringsfunksjoner | Snittet mellom gjeldende brukerrettigheter og ressursene som omfattes av denne autorisasjonen |
| /mcp/business | Forretningssystemoppdagelse, spørring, handlingsplaner, status og utførelse | Egen autorisasjon for forretningssystemer og publiserte kontrakter |
| Innebyggingsside for ontologiagenten | Bruk ontologidialogen i brukergrensesnittet for mennesker | Krever en reell innloggingsøkt; er ikke et inngangspunkt for å utveksle MCP-token uten innlogging |
Funksjonsklassifisering
- Grunnleggende lesing: ontologi og ressurser, graflokalisering, kunnskapssøk og fullstendig originaltekst, detaljer for autoriserte tabeller og Doris SQL.
- Separat delegering: dfc_search krever search:operate og bruker fortsatt den opprinnelige brukerens rettigheter og modellrettighetene.
- Betinget tilgjengelige funksjoner: analyse, vedvarende rapporter, artefaktkladder og anvendelse, spørring mot ontologimodeller og delegerte agentoppgaver.
- Utilgjengelige funksjoner: dfc_etl i Flash rapporterer bare capabilities og tilbyr ikke Heavy ETL-utførelse. AutoML og interne inngangspunkter til FocusCode-arbeidsområder inngår ikke i det offentlige Flash-API-et som denne håndboken beskriver.
Fullføringskriterier
Lesing av fakta krever en faktisk brukbar spørringskvittering eller en kvittering med fullstendig originaltekst; genererte kandidater må oppgis som ennå ikke anvendt; publisering krever en reell APPLIED-kvittering; ved avbrudd må det skilles mellom forespørsel og bekreftelse. Svartekst, HTTP 200, at verktøyet har tatt imot forespørselen, eller at modellen beskriver noe som «ferdig», er ikke alene bevis for at en forretningsoperasjon lyktes.
Det medfølgende reference/mcp-tool-catalog.json er en offline deklarasjonsreferanse for r56 og inneholder definisjoner av betinget aktiverte funksjoner; den er ikke en sanntids tools/list for noen bruker. Den komplette katalogen omfatter 28 kjerneverktøy for ontologi, 4 betingede kontrollerutvidelser og 8 verktøy på forretningssiden; det betyr ikke at alle er tilgjengelige som standard.
Rask tilkobling og funksjonsoppdagelse
Start med instansens offisielle domenenavn og oppdag faktisk tilgjengelige verktøy med minimale rettigheter.
- Få den offisielle HTTPS-rotadressen fra administratoren, og avklar hvilken ontologi eller hvilket forretningssystem du skal ha tilgang til. Ikke bruk eksempeldomener fra dokumentasjonen til å kalle ekte forretningssystemer.
- Konfigurer MCP-serveradressen som https://flash.example.com/mcp; Business Workspace bruker /mcp/business i samme domene.
- Utløs OAuth-innlogging og autorisasjon slik klienten støtter det, og kontroller ressurser og scope; ikke send brukernavn og passord til MCP.
- Bruk oppdagelse eller initialisering for den aktuelle protokollgenerasjonen, og les deretter tools/list og ressursbeskrivelser.
- Utfør først en liten skrivebeskyttet forespørsel og kontroller strukturerte resultater og feil, før du utfører brukerens mål.
Klientkonfigurasjonsutdrag
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Dette utdraget viser konfigurasjonsintensjonen for serveradressen; den konkrete konfigurasjonsfilstrukturen og OAuth-støtten avhenger av klienten. Ikke skriv ekte access_token, refresh_token, informasjonskapsler eller administratorpassord i offentlige filer.
Moderne protokolloppdagelse
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": {}
}
}
}Sjekk før integrasjon
- Ressursens rotadresse, OAuth-issuer og den eksterne adressen til den omvendte proxyen samsvarer.
- Klienten støtter den aktuelle protokollgenerasjonen, i stedet for alltid å sende initialize til det nye protokollinngangspunktet.
- Gjeldende autorisasjon er bundet til den nødvendige ontologien eller forretningssystemet.
- Tokenet er gyldig, og nye valgfrie scopes er eksplisitt autorisert.
OAuth-oppdagelse, registrering og autorisering
Bruk autorisasjonskode og PKCE; ikke eksponer produktets påloggingsinformasjon for agenten.
| Endepunkt | Metode | Formål |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Ressursoppdagelse for ontologi-MCP |
| /.well-known/oauth-protected-resource/mcp | GET | Kompatibel oppdagelse via ontologiressursens bane |
| /.well-known/oauth-protected-resource/mcp/business | GET | Ressursoppdagelse for forretnings-MCP |
| /.well-known/oauth-authorization-server | GET | Metadata for autorisasjonsserveren |
| /oauth/register | POST JSON | Dynamisk registrering av public client |
| /oauth/authorize | GET eller POST form | Innlogging, ressursvalg og autorisasjonsbekreftelse |
| /oauth/token | POST form | Innløsning av autorisasjonskode og rotasjon av refresh-token |
| /oauth/revoke | POST form | Tilbakekalling av token |
| /oauth/grants | GET | Innloggede brukere ser autoriserte tilkoblinger |
| /oauth/grants/revoke | POST form | Tilbakekall tilkoblingen via den eksisterende sideflyten |
Autorisasjonsrekkefølge
- Les metadata for beskyttede ressurser og autorisasjonsserver. En forespørsel uten token får 401 med WWW-Authenticate, som peker til adressen for ressursoppdagelse.
- Registrer eller bruk klientidentitet. I r56 bruker dynamisk registrering av public client token_endpoint_auth_method=none; en klienthemmelighet kan ikke erstatte PKCE.
- Generer tilfeldig state og code_verifier, og beregn S256 code_challenge.
- Åpne authorize-adressen som metadataene angir, og send response_type=code, client_id, nøyaktig redirect_uri, scope, resource, state, code_challenge og code_challenge_method=S256.
- Brukeren logger inn i DataFocus og velger ontologi eller forretningssystem. Klienten kan ikke forhåndsvelge ressurser brukeren ikke har tilgang til.
- Motta callback, verifiser state og issuer; innløs autorisasjonskoden med den opprinnelige code_verifier.
- Bruk kun access_token til MCP Bearer-autentisering. Fornyelse skjer via den opprinnelige OAuth-flyten, og det roterte refresh_token lagres sikkert.
Registreringseksempel
{
"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"]
}Callback for webklienter bruker HTTPS; native klienter kan bruke støttede loopback-adresser. Både autorisasjon og tokeninnløsning krever nøyaktig samsvar med den registrerte callback-adressen. Én Grant gjelder én beskyttet ressurs; ikke bland ontologi-scope og Business Workspace-scope i samme tilkobling.
Token-levetid
Standardverdiene på r56-serveren er 3600 sekunder for access token, 2592000 sekunder for refresh token og 300 sekunder for autorisasjonskoden; en distribusjon kan overstyre disse. Klienten må vurdere ut fra expires_in i tokensvaret og faktiske feil, og ikke hardkode standardverdiene. Ta i bruk det nye tokenet etter fornyelse; tilbakekalling av rolle, ressursrett eller Grant gjør at påfølgende kall avslås.
Scope, ressursgrenser og sanntidsrettigheter
Autorisasjonsomfanget delegerer eksisterende rettigheter, gir ingen rolleoppgradering og deler ingen forretningsstatus på tvers av Grants.
| Scope | Typiske funksjoner | Viktige begrensninger |
|---|---|---|
| ontology.metadata:read | Ontologi, ressurser og tabellstruktur | Ontologien og tabellene må ligge innenfor autorisasjonen og gjeldende leseomfang |
| ontology.graph:read | Grafsøk og naboer | Returnerer lokaliseringsinformasjon, ikke faktabevis |
| ontology.knowledge:read | Kunnskapslokalisering og fullstendig originaltekst | Kunnskapsbasens og dokumentets opprinnelige rettigheter gjelder fortsatt |
| ontology.table:query | SQL mot ontologitabeller og spørring mot publiserte modeller | Tabellspørring krever også metadata-scope; faktiske kilde- og kolonnerettigheter gjelder fortsatt |
| search:operate | Innebygde nøkkelordmodeller og økter | Separat, eksplisitt delegering; utføres med den opprinnelige modellens rettigheter og brukerens tabell- og kolonnerettigheter |
| etl:operate | Flash ETL capabilities | Gir ikke tilgang til Heavy ETL |
| authoring.contract:read | Betinget tilgjengelige modelleringskontrakter | Krever også funksjonsbryter og tilhørende ressurser |
| authoring.artifact:read | Lesing av kandidater, planer osv. innenfor gjeldende autorisasjon | Bundet til opprinnelig subjekt, Grant og ressurser |
| authoring.artifact:draft | Kandidatinnsending, forhåndsvisning osv. | Gir ikke autorisasjon til utførelse eller publisering |
| authoring.artifact:apply | Kontrollert planlegging og anvendelse | Krever fortsatt den opprinnelige forretningsrollen, policy og godkjenning |
| execution.script:draft | Bestemte skriptkladder | Gir ikke autorisasjon til faktisk skriptutførelse |
| datasource.http:read / draft / test / import | Betinget tilgjengelige funksjoner for HTTP-datakildeartefakter | Hver har egen bryter og krever de opprinnelige rettighetene |
Kombinasjonskrav for lesing
dfc_table detail krever ontology.metadata:read; query krever i tillegg ontology.table:query. dfc_ontology_query krever begge lese-scopene graph og knowledge. dfc_knowledge_search/detail krever knowledge. published_model/published_query går via table:query; candidate_query krever i tillegg authoring.artifact:read. Analyseverktøy kontrollerer også hvilke bevis-scopes som er tillatt; vedvarende rapporter krever metadata og table query.
Ikke hardkod standardautorisasjon
Standardsettet med ontologi-scopes i r56 inneholder table query; Search og ETL krever eksplisitt delegering. Avgjørende er likevel oppdagelsesmetadataene, autorisasjonssiden, faktisk tokenscope og tools/list. Påstander i eldre dokumentasjon om at «ontologi som standard aldri har SQL» eller «kun seks verktøy» beskriver ikke gjeldende implementasjon.
Statusisolering
Økter, rapporter, kandidater og handlingsplaner har hver sin eier og sitt omfang. Fornyelse av access token overfører ikke arbeid fra én Grant til en annen. Ikke slå sammen sessionId, reportId, planId, godkjenningstokens eller kildetokens returnert av en annen tilkobling inn i gjeldende tilkobling.
HTTP og moderne MCP-meldinger
Send riktig metadata for hver forespørsel og samsvarende rutinghoder, og håndter HTTP-resultater og verktøyresultater hver for seg.
| Element | Atferd i r56 |
|---|---|
| Overføring | Tilstandsløs Streamable HTTP, POST JSON-RPC |
| Støttede identifikatorer | 2026-07-28 samt 2025-11-25 2025-06-18 2025-03-26 |
| Moderne metoder | server/discover tools/list tools/call resources/list resources/read, gjøres tilgjengelig ut fra faktiske funksjoner |
| Økthoder | Ingen Mcp-Session-Id tildeles |
| GET og DELETE | /mcp og /mcp/business returnerer 405 |
| SSE-varsler fra serveren | Tilbys ikke av de to offentlige MCP-inngangene |
| Katalogbuffer | Moderne oppdagelse og listing returnerer ttlMs=60000 og cacheScope=private |
| Vanlige resultater | Moderne resultater inneholder resultType=complete og metadata for tjenesteidentitet |
Innhold som må samsvare
- MCP-Protocol-Version må samsvare med io.modelcontextprotocol/protocolVersion i params._meta.
- Mcp-Method må samsvare med method i JSON-RPC.
- Mcp-Name i tools/call må samsvare med params.name; navnehodet i resources/read må samsvare med URI-en.
- Hver moderne forespørsel inneholder et io.modelcontextprotocol/clientCapabilities-objekt; oppgi også standard clientInfo, slik at klienten kan identifiseres.
Eksempler på kall
{
"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": {}
}
}
}De tilsvarende HTTP-hodene er Mcp-Method: tools/call og Mcp-Name: dfc_ontologies. Alle ACCESS_TOKEN i eksemplene er plassholdere. Ikke legg Bearer-token i URL-er, JSON-parametere eller buffernøkler.
Lesing av resultater
Behandle først HTTP-statusen, og kontroller deretter JSON-RPC error; ved result fortsetter du med å kontrollere isError. Vellykkede verktøyresultater gir vanligvis structuredContent, samt tekstinnhold som inneholder samme forretnings-JSON; les helst den strukturerte kanalen, og unngå å summere text og structuredContent dobbelt som to uavhengige fakta. HTTP 200 kan inneholde en verktøyfeil.
Offentlige ressurser og UI
De innebygde dokumentasjonsressursene er ikke avhengige av MCP Apps. Business Workspace-inngangen får derfor ikke ontologidokumentasjonsressurser. Klienter som støtter visualisering, bør oppdage tilhørende UI via faktiske funksjoner og verktøyets _meta, og ikke gjette ressurs-URI-er som ikke er returnert.
Kompatibilitet med eldre protokollklienter
Hold protokollgenerasjonen konsistent i klienter som fortsatt bruker initialiseringshåndtrykket.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Send initialize, og les protokollversjonen og capabilities som serveren har forhandlet fram.
- Send nødvendig varsel om fullført initialisering i henhold til klientens protokoll; varsler gir ingen vanlige verktøyresultater.
- Bruk tools/list til å lese verktøyene som er autorisert nå, og send deretter tools/call.
- Hold hoder og meldinger konsistente med protokollgenerasjonen for gjeldende forespørsel; ikke bruk den eldre initialize- eller ping-flyten med 2026-07-28-meldinger.
Den eldre protokollen bruker fortsatt samme Bearer/OAuth, rettigheter og verktøykontrakter. Det betyr ikke at serveren nødvendigvis tilbyr langvarige SSE-tilkoblinger av eldre type eller Mcp-Session-Id; de offentlige tjenestene i r56 forblir tilstandsløse.
Protokollfeil
| Scenario | Typisk resultat | Løsning |
|---|---|---|
| Moderne hoder og meldinger samsvarer ikke | HTTP 400 JSON-RPC -32020 | Korriger hoder, metadata og verktøynavn |
| Versjon som ikke støttes | -32022 med en liste over støttede versjoner | Velg en faktisk støttet protokoll |
| Ukjent metode | JSON-RPC -32601; moderne forespørsler kan gi HTTP 404 | Kontroller protokollgenerasjon og metode |
| Manglende eller ugyldige parametere | JSON-RPC parameterfeil eller verktøy-isError | Korriger i henhold til faktisk inputSchema |
Velg riktig verktøy og beviskanal
Rut ut fra det uløste forretningsspørsmålet; ikke gjenta bevisinnhenting med en fast kallkjede.
| Oppgave | Foretrukket verktøy | Bevis som kreves for fullføring |
|---|---|---|
| Oppdage autoriserte emner og ressurser | dfc_ontologies dfc_ontology_resources | Faktisk ressurs-ID-type og gjeldende synlighetsomfang |
| Tabellstatistikk og TopN | dfc_table query | Kvittering for vellykket kjøring og fullstendig evidenceRows |
| Slå opp regler, kontrakter eller rapporter | dfc_ontology_query eller knowledge search/detail | Fullstendig, autorisert originaltekst som kan brukes som fakta |
| Lokalisere grafobjekter | dfc_ontology_graph search/neighbors | Lokaliser den faktiske kilden, og hent deretter tilhørende fakta |
| Innebygd nøkkelordinteraksjon | dfc_manual og deretter dfc_search | Faktiske resultater i den opprinnelige modellen og forretningsrammen |
| Fusjonsanalyse og rapportering | dfc_analysis_* eller dfc_report_* | Den faktiske tilstanden for de ulike strukturerte grenene og dokumentbevisene |
| Endre presentasjon eller ontologimodell | dfc_authoring_* og artifact-verktøy | Bekreft kandidat, plan, godkjenning og faktisk anvendelse hver for seg |
| Utføre forretningskommandoer | dfb_* i /mcp/business | Publiserte kontrakter og den opprinnelige ActionPlan-kvitteringen |
Unngå unødvendige kall
Når du allerede har en gjeldende, fullstendig og autorisert tabellstruktur, trenger du ikke hente detail på nytt ved hver spørring; når du har pålitelig lokalisering og bevis, ikke gjenta det samme søket. Gjør avgrensede supplerende søk når en manglende dimensjon trengs. Når en feil uttrykkelig ikke kan prøves på nytt, løs mangelen først; ikke la «prøv én gang til» erstatte en vurdering.
Utelatt i Flash
dfc_etl capabilities kan returnere available=false og ETL_NOT_INCLUDED_IN_OT_FLASH. Den statiske beskrivelsen av innebygde ETL-funksjoner er ment som referanse på tvers av produkter, beviser ikke at ETL er installert i Flash, og tillater ikke at agenten automatisk går over til Heavy eller en annen leietaker for å utføre den.
Ontologiressurser og ID-typer
Hent først de faktiske ressurskoordinatene for å unngå å blande lagringsnavn, dokument-ID-er og kunnskapsbase-ID-er sammen.
- Kall dfc_ontologies og bla gjennom ontologiene som omfattes av denne autorisasjonen og fortsatt kan leses, ved hjelp av page og pageSize.
- Kall dfc_ontology_resources med en ekte ontologyId; velg tables, answers, pinboards, documents og knowledgeBindings etter behov.
- Behandle sideinndeling for hver ressurstype separat. pageSize er maksimalt 100; ikke anta hele ressursomfanget ut fra første side.
- Lagre typen som ressursen deklarerer, og den opprinnelige ID-en, og bruk dem uendret i senere kall.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Koordinater | Kilde | Kan ikke erstatte |
|---|---|---|
| ontologyId | Autorisert ontologiliste eller gjeldende gyldig kontekst | ID-en til en annen ontologi |
| Tabellressurs-id | tables-listen eller pålitelig kontekst | physicalName eller vist tabellnavn |
| tblDisplayName colDisplayName | Gjeldende tabell- og kolonnemetadata | Gjettet fysisk SQL-identifikator |
| knowledgeId | knowledgeBindings eller kvittering fra faktisk kunnskapssøk | Dokumentressurs-id |
| assetId documentId chunkId evidenceId | Samme faktiske lokaliseringskvittering | Felter satt sammen fra ulike lokaliseringsresultater |
| rid revisionId releaseId | Publisert modell eller kandidatkontekst på serversiden | Selvgenerert ID eller latest |
Presisjonskonvensjoner
Alle 64-biters ressursidentifikatorer bør helst angis som desimalstrenger og ikke konverteres via Number i JavaScript. At enkelte forretnings-Schemaer godtar string eller integer, betyr ikke at heltallspresisjon kan droppes. Opaque locator, UUID, hashverdier og engangstokens lagres også som de er.
Doris-tabellspørrings- og strukturkontrakt
Utfør skrivebeskyttet SQL på autoriserte tabeller, og bevar utdatasemantikk, eksakte verdier og fullstendighet.
Les strukturen
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}detail bruker den faktiske tabellressurs-ID-en. Kontroller schemaComplete, tblDisplayName, colDisplayName i columns og den autoritative sqlDataType, samt den returnerte queryContract. dataType er kun en kompatibilitetstilordning; det fysiske lagringsnavnet er ikke tabellnavnet du bruker i SQL-en du sender inn.
Utfør spørringen
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}SQL-begrensninger
- Bruk viste tabell- og kolonnenavn, og siter identifikatorer med doble anførselstegn. Forespørselen er én skrivebeskyttet Doris-spørring innenfor ontologiens omfang.
- List utdataene eksplisitt; SELECT * og table.* er forbudt; de kan ikke omgå registrerte kolonnerettigheter via fysiske kolonner.
- Bruk eksplisitt JOIN ... ON for koblinger; NATURAL JOIN og JOIN USING avvises.
- Gyldige skrivebeskyttede uttrykk som flerdimensjonal aggregering, CTE, vinduer, CASE og COUNT(DISTINCT ...) kan brukes; at semantisk validering ikke dekker et uttrykk, betyr ikke at kjøring er generelt forbudt.
- Fullfør aggregering, sortering og rangering i SQL først, og legg deretter på resultatgrensen. maxRows er som standard 100, maksimalt 200.
Dato og tidssone
| Type eller mål | Form | Merk |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) og CURRENT_DATE | Ikke anta datotype direkte fra en tekstliteral |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) og CURRENT_TIMESTAMP | Kontroller kildetidssone og økttidssone |
| Relativ tid | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Bruk den tilsvarende funksjonen for gjeldende dato eller tidsstempel |
| Tidsgruppering | YEAR(column) eller DATE_TRUNC(column, 'month') | Gi hver utdatakolonne et unikt alias; queryContract er avgjørende |
SQLite-funksjonen DATE('now', ...) er ikke Doris-datokontrakten for denne inngangen. Ikke bruk SQLite-metoden som dokumentasjonen bruker til offline kontroll av eksemplene, i SQL som kjøres online.
Les kvitteringen for v8-spørringen
evidenceRows er agentens eneste kanal for raddata; rådata er ikke tilgjengelig for agenten. SQL-tall kodes som eksakte desimalverdier i JSON-strenger; bruk resultColumnContracts for å fastslå deres numeriske og forretningsmessige type, og ikke tolk tallet i JSON som VARCHAR bare fordi det er kodet som en streng. Les executionReceipt, fullstendighet og trunkeringsinformasjon, og ta vare på kildeinformasjon som evidenceRowsSha256.
Spørringsutdata med en refererbar kjøringskvittering kan siteres slik de er; kun semantikk som er verifisert på serversiden, kan autorisere påfølgende deterministiske sekundærberegninger. Ikke gjett «kumulativ saldo», «sluttverdi» eller «valuta» ut fra feltnavn, og ikke legg til enheter på egen hånd. Resultater med null rader, feil eller trunkering må ikke beskrives som fullstendig statistikk.
Flerdimensjonal topp 3 og håndtering av trunkering
Besvar rangeringsspørsmål med aggregering og vindusfunksjoner på serversiden, og ikke gjør sekundærberegninger på ufullstendige resultater.
Det medfølgende examples/top3.sql bruker eksempeltabellen: det aggregerer først etter 区域, 类别 og 产品, kjører deretter ROW_NUMBER innenfor hver 区域 og 类别, og bruker 产品-navnet som stabil rekkefølge ved like beløp. Å be om maxRows=100 er nok til eksempelets 36 rader; for andre forretningsdata må dette vurderes ut fra det faktiske antallet grupper.
- Hent den faktiske strukturen og gjeldende forretningsdefinisjon, og avklar 币种, periode, 订单状态 og regler for like rangeringer.
- Send inn SQL som aggregerer og rangerer på serversiden. Ikke spør først bare om totalen per 区域 og bruk den deretter som rangering av 产品 per 类别.
- Kontroller kontrakten for utdatakolonner mot faktisk evidenceRows, og bekreft at resultatet dekker alle nødvendige grupper.
- Hvis du oppdager trunkering, kjør avgrensede partisjonsspørringer innenfor grensene serveren støtter, for eksempel en komplett topp 3 per 区域; bruk samme forretningsdefinisjon i hver spørring.
- Hvis kildeperioden har endret seg, spør på nytt og angi tydelig den nye versjonen; ikke bland ulike dataversjoner eller utløpte markører.
Feilgjenoppretting
TABLE_SCHEMA_INCOMPLETE krever at du retter forespørselen eller henter den fullstendige strukturen; feil som ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID håndteres i henhold til returnert errorCode, retryable og remediation. Ikke hevd at «alle flerdimensjonale GROUP BY eller vindusfunksjoner er forbudt», og ikke finn på rangeringer uten spørringsresultater.
Kunnskapssøk: fullstendig originaltekst og kvalifisering som bevis
Hold lokalisering, lesing og sitering av fakta adskilt, og ta vare på kilde og fullstendighet.
To vanlige veier
| Vei | Formål | Nøkkelpunkter |
|---|---|---|
| dfc_ontology_query | Søk i ontologibundet kunnskap, eventuelt kombinert med grafruting | Kontroller at canonical answerContextItems er fullstendige, og kontroller kvalifisering som bevis |
| dfc_knowledge_search → dfc_knowledge_detail-chunk | Lokaliser eksplisitt med søk, og les deretter de valgte chunkene | Søkeforhåndsvisningen brukes ikke som fakta; les den fullstendige originalteksten for samme lokalisering |
{"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>"
}}Vilkår for bruk som fakta
- Kontroller gjeldende ACL, innholdets fullstendighet og serverens canonicalFactEligible, citationEligible eller tilsvarende kjøringskontrakt.
- Fullstendig innhold er bundet til contentSha256. Trunkering, utelatelser på grunn av budsjett eller innhold av lav kvalitet må håndteres ut fra de faktiske feltene.
- Dokumentmetadata, page_context, graflokaliseringsinformasjon, søkeoppsummeringer og forhåndsvisninger kan ikke erstatte canonical-originalteksten.
- Kopier helst evidenceId; trenger du chunkId og documentId, må de komme fra samme lokaliseringsresultat – ikke sett dem sammen fra ulike resultater, og ikke finn på verdier.
Grafruting
search/neighbors-resultatet er lokaliseringsinformasjon. Send bare routeLocator-objektet som serveren har returnert fullstendig, inkludert binding-, versjons- og bevisfelt, videre til ontologispørringen (query). Ikke pakk en assetId eller knowledgeId selv inn som en lokator utstedt av serveren, og ikke send tilbake kildebevis som modellen har påstått.
Strukturert dokumentgjenoppretting
dfc_ontology_query har structuredPlan, en begrenset gjenoppretting med deterministisk validering beregnet spesielt for tabeller i uregelmessige dokumenter. Bruk kun planen serveren har deklarert, og først etter at gjeldende executionContractSha256, tableIndex, kolonner og den fullstendige tabellen er returnert. Vanlige, allerede importerte forretningstabeller skal spørres via dfc_table SQL; ikke bruk gjenoppretting av Markdown-tabeller som en kanal for å omgå autorisasjonen for tabellspørringer.
Søkestrategi
knowledgeIds utelates vanligvis for å dekke gjeldende aktive bindinger; hvis du oppgir den, bruk kun faktiske kunnskapsbase-ID-er fra knowledgeBindings. Ikke bruk en dokumentressurs-ID som kunnskapsbase-ID. Gjør nye, avgrensede søk ut fra det som fortsatt er uavklart, og unngå nøyaktig gjentatte søk som ikke gir nye bevis.
Innebygde Search-modeller og økter
Bruk nøkkelordprotokollen til Rust Search via dfc_search, og vent på sluttstatusen i den opprinnelige forretningsrammen.
Les dokumentasjonen først, og oppdag deretter funksjonene
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search krever en eksplisitt search:operate. Den kapsler inn den opprinnelige nøkkelord-WebSocketen og skriver ikke om nøkkelord til SQL- eller LLM-forespørsler. Økten er bundet til gjeldende leietaker, bruker, Grant, klient og modell, og de opprinnelige tabell- og kolonnerettighetene kontrolleres på nytt ved hver operasjon.
Minimal øktflyt
{"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 bruker 1 til 100 faktiske tabell-ID-er du har rettigheter til, eller model_read leser en eksisterende sourceToken.
- open returnerer kun initializationSent; poll først, les det opprinnelige init-forretningssvaret og bekreft at det lyktes.
- Les assist og forslag, og send deretter en støttet opprinnelig message. I query datas er isNl fastsatt til false av wrapperen.
- Fortsett å lese frames, og skill mellom forslag, parsing, mottak og endelig forretningsresultat.
- Avslutt med close; bruk cancel når du må avbryte, og kontroller ut fra den faktiske oppgavestatusen om den virkelig er avsluttet.
| action | data | Betydning |
|---|---|---|
| capabilities | Utelatt eller tomt objekt | Les handlinger, kommandoer, TTL og overføringsbeskrivelser |
| model_create | tableIds-matrise | Opprett en autorisert modell for gjeldende bruker |
| model_read | sourceToken | Les modellen, og filtrer bort kolonner uten rettigheter og sensitiv kildekonfigurasjon |
| open | sourceToken og valgfritt language | Opprett en innebygd økt og send init |
| request | sessionId og message | Send en protokollmelding i det opprinnelige type/datas-formatet |
| poll | sessionId og waitMillis 0 til 30000 | Hent gjeldende bufrede rammer og vent eventuelt i begrenset tid |
| cancel close | sessionId | Lukker denne innebygde økten; bekrefter ikke BI-sluttstatusen |
Støttede opprinnelige kommandoer
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteKommandoenes store/små bokstaver og datas-strukturen følger gjeldende capabilities og den opprinnelige øktprotokollen. Ikke legg til ikke-eksisterende handlinger i request; for eksempel må stavemåten disambiguite beholdes slik den faktiske protokollen tilsier. En melding er maksimalt 256 Ki tegn.
Økt og fullstendighet
Øktens TTL er 10 minutter, og økten beholdes bare så lenge gjeldende prosess lever; den er ikke en oppgave som kan gjenopprettes vedvarende. Bufferen rommer maksimalt 256 rammer og er begrenset av minnetak; når bufferOverflow=true, kan allerede hentede rammer ikke behandles som et fullstendig resultat. Etter en overføringsfeil skal du først polle den opprinnelige økten, og ikke blindt sende på nytt en spørring som kanskje allerede er utført.
Gjeldende wrapper tilbyr ikke lagring av svar eller pinboards, lesing/skriving av historikk eller gjenoppretting av vilkårlig kontekst. Eksistensen av exportContext betyr ikke at vilkårlig kontekst kan gjenopprettes på egen hånd. Når resultater skal lagres, bruk de opprinnelige ressursfunksjonene som instansen faktisk gjør tilgjengelige; ikke finn på action-verdier.
Språk- og regionkonvensjoner
Hold grensene klare mellom UI-locale, spørringsordbok, svarspråk og opprinnelige feltnavn.
Prioritetsrekkefølgen er: eksplisitt forespurt språk, applikasjonens systemspråk og deretter locale på noden som faktisk utfører forespørselen. En utelatt verdi, null, en tom streng eller bare mellomrom gir ikke automatisk tilbakefall til kinesisk. De regionale verdiene i languageRegistry må beholdes nøyaktig; en-GB, fr-CA, pt-BR, es-US og ar-AE må ikke vilkårlig slås sammen med en annen region.
| Språk eller region | Spørrings-locale | Beskrivelse |
|---|---|---|
| Forenklet kinesisk, tradisjonell kinesisk | zh-CN zh-Hant | De opprinnelige kinesiske reglene skiller seg fra katalogen for tradisjonell kinesisk |
| Engelsk (USA, Storbritannia, Australia, Canada) | en-US en-GB en-AU en-CA | UI- og nøkkelordpakker kan deles; regionmetadata beholdes |
| Tysk, italiensk, russisk | de-DE it-IT ru-RU | Bruk forslagene fra gjeldende økt |
| Spansk (Spania og Latin-Amerika) | es-ES es-US | Produktets region-ID er es-US |
| Fransk (Frankrike og Canada) | fr-FR fr-CA | Region-ID-er slås ikke sammen |
| Portugisisk (Portugal og Brasil) | pt-PT pt-BR | Katalog- og regionkonvensjoner beholdes hver for seg |
| Nederlandsk, dansk, norsk, finsk, svensk | nl-NL da-DK nb-NO fi-FI sv-SE | Norsk er bokmål |
| Japansk, koreansk | ja-JP ko-KR | Ikke del opp ord selv etter engelske regler for mellomrom |
| Arabisk (Saudi-Arabia og De forente arabiske emirater) | ar-SA ar-AE | Grensesnittbeskrivelser støtter RTL; protokollidentifikatorer reverseres ikke |
Bruk nøkkelordkatalogen
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}Den statiske nøkkelordkatalogen i dfc_manual omfatter bare de locales som er eksplisitt oppført; utelates locale, brukes den engelske referansen. Dette er en standardverdi for referansen, ikke en regel for hvordan spørringsspråket tolkes. Når en statisk katalog ikke er tilgjengelig for en regionvariant, hent faktiske forslag via gjeldende økts assist, og ikke forfalsk aliaser eller tilbakefallsresultater. names kan ha maksimalt 32 elementer per kall.
Innhold som ikke skal oversettes
- Tabeller, kolonner, enum-verdier, kundenavn, formelnavn og andre faktiske modellstrenger.
- Verktøynavn, action, scope, Schema-felter, feilkoder og statusverdier.
- Ressurs-ID-er, hasher, opake lokatorer og referanser utstedt av serveren.
Et tysk spørsmål kan for eksempel spørre mot den kinesiske visningskolonnen «销售金额». Endrer du den til et tysk kolonnenavn, blir det en annen identifikator, ikke en oversettelse av grensesnittet. Etter bytte av språk må du initialisere økten på nytt eller oppdatere den i henhold til den opprinnelige protokollen, og hente forslag og tvetydighetskandidater på nytt.
Fusjonsanalyse og interaktive resultater
Ta vare på autorisasjon, versjon, gren og bevisstatus i de betinget tilgjengelige analyseverktøyene.
dfc_analysis_* styres av datafocus.mcp.analysis.tools.enabled. Den strukturerte delen går fortsatt via den autoritative Search-spørringen og gjeldende radpolicy; dokumentdelen henter på nytt den fullstendige originalteksten under gjeldende ACL. De er ikke innganger for åpen SQL, vilkårlige instruksjoner eller injeksjon av vilkårlige filtre.
| Verktøy | Formål | Nødvendige koordinater |
|---|---|---|
| dfc_analysis_ask | Still et analysespørsmål på naturlig språk | ontologyId question, valgfritt language sessionId |
| dfc_analysis_result_get | Les tidligere returnerte resultater | ontologyId sessionId resultId |
| dfc_analysis_refine | Still oppfølgingsspørsmål eller gjør endringer basert på det nyeste fullstendige resultatet | Opprinnelig resultat, expectedRevision og stabil idempotensnøkkel |
| dfc_analysis_page | Hent én side av en gren fra serveren | Opprinnelig gren og resultatversjon pageNo pageSize |
| dfc_analysis_cancel | Avbryt et resultat som fortsatt er under arbeid | Opprinnelig økt og resultat |
| dfc_analysis_close | Frigi økter som ikke lenger er i arbeid | Opprinnelig økt |
Start analyse
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Les returnert sessionId, resultId, status og revision; les det opprinnelige resultatet på nytt ved behov.
- Kontroller status, fullstendighet, radpolicy og kilde for hver strukturerte gren hver for seg; én fullført gren betyr ikke at hele analysen er fullstendig.
- Kontroller dokumentbevis, faktaregister, kvalifisering for sitering og begrensninger. Tekst som modellen genererer, kan ikke alene heve kvalifiseringen som bevis.
- Ved oppfølgingsspørsmål: baser deg på det nyeste fullstendige resultatet og send expectedRevision; gjenbruk samme idempotensnøkkel ved forsøk på nytt for samme endring.
- Bekreft før lukking at økten ikke lenger jobber; å avbryte og å lukke er ulike handlinger.
Kontrollert filtrering og sideinndeling
filter_patch bruker branchId, fieldRef, valueRef og tillatte operatorer som serveren har oppgitt; den nåværende typede filtreringen deklarerer kun EQ. Det er forbudt å erstatte opaque-referanser med rå SQL, tableId, columnId eller et filtertre konstruert på klientsiden. For sideinndeling starter pageNo på 1 og er maksimalt 10000; pageSize er maksimalt 100.
Funksjonshint og atferd
Verktøyenes annotations er hint til klienten, ikke sikkerhetsautorisasjon. Noen generiske maler bruker readOnlyHint og kan ikke erstatte en vurdering av den faktiske handlingen; å avbryte, lukke og opprette rapporter endrer den tilhørende arbeidstilstanden. Følg alltid verktøyets semantikk, brukerens mål og serverens rettigheter.
Vedvarende visualiseringsrapporter og MCP Apps
Opprett rapporter som kan gjenopptas, og les resultatene og det interaktive grensesnittet innenfor gjeldende rettigheter.
dfc_report_* styres av datafocus.mcp.analysis.report-tools.enabled og krever metadata- og table query-scope. I motsetning til en Search-økt som bare lever i prosessen, bruker rapporter en vedvarende reportId. At rapporten er vedvarende, betyr ikke at rettighetene slutter å bli kontrollert.
{"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>"
}}Arbeidsflyt
- Bruk en stabil idempotencyKey ved oppretting, med 8 til 128 støttede tegn.
- Lagre reportId, poll status, og kontroller faktisk tilstand: fullført, mislykket, delvis fullført eller avbrutt.
- Ved lesing av resultater: kontroller strukturerte grener, visualiseringer, faktakilder, dokumentreferanser og fullstendighet.
- Avbryt rapporter som ikke er ferdige, med den opprinnelige reportId; ikke opprett en annen rapport i stedet for å avbryte.
- Etter tidsavbrudd i nettverket: les først statusen til den opprinnelige rapporten; gjentatt sending med den opprinnelige idempotensnøkkelen skal ha samme forretningshensikt.
MCP Apps
Klienter som støtter UI-utvidelser, leser rapportsider via verktøyets _meta og faktisk ressursoppdagelse. Den vedvarende rapportsiden for r56 er ui://datafocus/analysis-report/v16/index.html; interaktiv analyse bruker tilhørende referanser til serverressurser. Klienten skal ikke hardkode disse i stedet for å bruke verktøyets returverdier. Strukturerte resultater kan leses også uten UI-utvidelser.
Kildebinding
Ved lesing av rapporter kontrolleres Grant, ontologi, binding av forespørselens Origin og gjeldende tabellrettigheter på nytt. Integrasjon på tvers av opphav (cross-origin) i nettleseren krever et godkjent, faktisk opphav; klienten skal ikke omgå bindingen med en forfalsket Origin. En gammel reportId er verken en varig offentlig lenke eller en tilgangslegitimasjon på tvers av brukere.
Artefaktkladd, forhåndsvisning, plan og anvendelse
Overlat generert innhold til serverens egen normalisering, validering og godkjenning; ikke la modellen endre produksjonsressurser direkte.
Artefaktverktøy krever authoring-funksjonen aktivert, en faktisk artefakttype, relevant scope og den opprinnelige skriverettigheten som administrator. Standardtypekonfigurasjonen er CONTROL_PANEL_SPEC og VIEW_SPEC; andre skjema-, HTTP-kilde- eller skripttyper styres i tillegg av egne konfigurasjoner. Flash har ikke AutoML, så tilhørende typer er ikke oppført som tilgjengelige artefakter i denne versjonen.
- dfc_authoring_capabilities leser kontraktene og handlingene som er tilgjengelige for gjeldende Grant.
- dfc_artifact_context henter avgrenset kontekst, contractVersion, contextHash, baseArtifactHash og baseArtifactVersion.
- Generer kandidater på klientsiden ut fra den faktiske kontrakten, uten å kjøre koden i dem.
- dfc_artifact_submit sender inn opprinnelig kontekst og kandidat, beholder instruction uendret og bruker en stabil clientRequestId.
- Les proposalId, candidateHash, valideringsresultatet og forhåndsvisningen; revider kandidaten ved faktiske feil, og ikke forfalsk en bestått-status fra serveren.
- Trenger du en ny forhåndsvisning, bruker du dfc_artifact_preview med samme kandidathash.
- dfc_artifact_plan oppretter en uforanderlig plan med den faktiske kandidaten, målversjonen og en idempotensnøkkel.
- Håndter godkjenningen via den opprinnelige interaktive godkjenningen eller en allerede autorisert policy, og kall deretter dfc_artifact_apply; bare en APPLIED-kvittering betyr faktisk anvendelse.
Minimal kontekstforespørsel
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC bruker gjeldende autoriserte projectId; ved redigering av en eksisterende artefakt brukes den faktiske artifactId. Felter som variables, previewInput og viewport oppgis i henhold til den returnerte kontrakten; ikke gjett eller konstruer kandidatens interne struktur.
Samtidighet og forsøk på nytt
Planen binder målversjon, kandidathash og idempotensnøkkel. Når målet er endret, kan den gamle planen ikke lenger anvendes; les konteksten på nytt og håndter faktiske konflikter. Et tidsavbrudd i transporten (transport timeout) beviser ikke at operasjonen mislyktes; spør først med dfc_artifact_status etter den opprinnelige proposalId eller planId. READY er ikke APPLIED.
Godkjenning og automatiske policyer
Generelle artefaktplaner krever den opprinnelige manuelle godkjenningen. Planer som oppfyller ontologiens policy for automatisk publisering, håndteres i henhold til approvalMode; brukeren trenger ikke å signere en ekstra godkjenning som agenten har funnet på. approvalToken er materiale utstedt av serveren og kan ikke erstattes av en streng som agenten skriver selv; faktisk inputSchema og planens kvittering bestemmer påkrevde felt.
Oppretting av ontologikandidater og publiseringskontrakter
Bruk ontologideklarasjoner og publiseringskonfigurasjoner med egne versjoner; ikke bruk kontrakter for vanlige visningsartefakter på modellpublisering.
Opprett kandidat
Ontologibeholderen må allerede eksistere og ligge innenfor Grant. Bruk dfc_ontology_table_schema til å kontrollere gjeldende strukturerte kildefelter og v4 Binding-fingeravtrykk; et felt kan oppgis med bare sourceField, slik at typen oppdages automatisk. Eksplisitt DECIMAL-deklarasjon krever gjeldende presisjon og antall desimaler; andre typer skal ikke ha disse to feltene.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Kandidat- og publiseringskonfigurasjon
| Kontrakt | Formål | Nøkkelgrenser |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Opprett kandidat fra lokale deklarasjoner | Faktiske autoriserte kilder, kompilering på serveren; godtar ikke fullføringsbevis |
| ontology-workspace-create-mcp-submit-v2 | Blanding av lokale og presise publiserte referanser | Oppgi presise releaseSelections og avhengighetene i lukkingen |
| ontology-publication-mcp-submit-v1 til v3 | Bind en eksisterende kandidat til en forespørsel om publiseringsplan | Eksplisitte koordinater; mål, kilde, godkjenning og validering gjenopprettes av serveren |
| ontology-publication-mcp-submit-v4 til v6 | Separat aktiverte konfigurasjoner for automatisk publisering | Brukes bare når capabilities og det faktiske schemaet deklarerer dem |
| ontology-initial-activation-retirement-submit-v1 | Kontrollert avvikling av initial aktivering | Egen plan, ny manuell godkjenning og presist omfang |
Publiseringsrekkefølge
- Hent den gjeldende kandidatens workspaceId, workspaceRevision, candidateHash og faktisk kilde.
- Velg kontraktversjon ut fra serverens funksjoner; send inn koordinater som releases og selection, uten felter som selv hevder «godkjent» eller «bestått».
- Ta vare på proposalId returnert av submit og den opprinnelige idempotencyKey. submit og MODEL_PLAN er ulike faser av samme forespørsel.
- Kall dfc_artifact_plan med den opprinnelige kandidaten, målversjonen og samme idempotensnøkkel.
- PLANNING_INCOMPLETE betyr bare at ingen gyldig plan foreligger ennå; VALIDATION_UNSATISFIED betyr at gjeldende validering fortsatt har mangler; håndter dette i henhold til nextAction.
- Når planen er opprettet, fortsetter du i henhold til HUMAN_REQUIRED eller POLICY_AUTO, med de opprinnelige godkjennings- og publiseringsfunksjonene.
- Bekreft resultatet med APPLIED-kvitteringen og påfølgende lesing av den faktisk publiserte modellen og autoriserte spørringer.
Tidsavbrudd og gjenoppretting
Etter PLAN-tidsavbrudd leser du den opprinnelige proposalId. MODEL_PLAN_SUBMITTED er en forespørsel som ikke er fullført; MODEL_PLAN_COMPLETED betyr at den opprinnelige kvitteringen skal gjenopprettes med opprinnelige koordinater og opprinnelig nøkkel, ikke at klienten skal lage en ny forespørsel. Mangler i den endelige valideringen kan ikke gjøres om til godkjent publisering ved å bytte nøkkel eller sende inn på nytt.
Menneskers forretningsrettigheter
instruction og deklarasjoner fra agenten er inndata fra agenten, ikke en policy signert av et menneske. MODEL_AUTHOR, MODEL_PUBLISH, delegering av automatisk publisering, forretningsbekreftelse, tillit til offentlige nøkler, budsjett og kilde-ACL bestemmes fortsatt av de opprinnelige mekanismene. Klientfelter kan ikke erstatte disse faktaene.
Publisert modell, kandidatspørring og referanselukking
Bruk publisert forretningskunnskap med presis versjon, og bevar den midlertidige karakteren til upubliserte kandidater.
dfc_ontology_graph: published_model, published_query og candidate_query er betinget tilgjengelige strukturerte konfigurasjoner, ikke synonymer for vanlig search/neighbors. De autoriseres i henhold til table query og nødvendige modelleringsleserettigheter; grafsynlighet kan ikke erstatte tabellrettigheter.
Les publisert modell
- Når verktøyets action-enum faktisk inneholder published_model, sender du en faktisk committed releaseId.
- v1 returnerer autoriserte spørringsmaler; v2 legger til presise PERSISTED-referanser og releaseSelections; v3 legger til avhengighetsreferanser, presis domainRef og kompakte bindingsmaler.
- Velg objekt, egenskap, Binding, scope og versjon fra faktiske returverdier; ikke generer RID-er, og ikke bruk latest.
- Send inn faste typede spørringer for published_query; resultatene må fortsatt passere gjeldende kilde- og feltautorisasjon.
Kandidatspørring
candidate_query bruker faktiske workspaceId, revision, candidateHash og kandidatdeklarasjoner. Når publiserte referanser blandes inn, brukes tilsvarende v2-typede LOCAL/PERSISTED-koordinater og presise valg. Kandidatresultater er alltid upubliserte og midlertidige og skal ikke behandles som kunnskap bekreftet av virksomheten.
Delvis vedlikehold og lukking
Velg kun de transitive avhengighetene kandidatroten trenger, og sørg for at hver publiserte referanse har presis releaseSelections. Å kopiere den publiserte teksten, sende inn bare én samling ID-er eller utvide til alle historiske ressurser erstatter ikke kontroll av gjeldende avhengigheter og kilder.
query for disse actions er versjonerte, typede objekter og aksepterer ikke SQL, fysisk tabell-ID eller kildetabellnavn som erstatning for forretningsreferansene deres. Metadatamaler og grafresultater er i seg selv ikke kvalifisert som faktareferanser.
Delegerte oppgaver for ontologiagenten
Gjenoppta arbeid med vedvarende oppgaver og opprinnelig Grant; ikke behandle agentens instruksjoner som menneskelig godkjenning.
dfc_ontology_agent vises kun når faktisk Pi Runtime og tilhørende rettigheter er tilgjengelige. QUERY bruker lesefunksjoner; AUTHORING krever dessuten modelleringsrolle og tilsvarende authoring-scope. Den åpner ikke en egen, ubegrenset utførelsesmotor.
{"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>"
}}Strengt parametersett
start bruker contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel bruker contractVersion, action, ontologyId, runId. Serveren kontrollerer det eksakte feltsettet for hver action. instruction kan ha maksimalt 16000 tegn; nøkkelen består av 1 til 128 støttede tegn og må begynne med en bokstav eller et siffer.
Gjenoppretting og avbrudd
- Ta vare på den opprinnelige runId, Grant, mode og idempotensnøkkel.
- Samme nøkkel med samme instruction gjenoppretter samme run uten å sende inn en annen oppgave; samme nøkkel med endret instruksjon avslås.
- status spør etter tilstanden til den opprinnelige oppgaven. Også etter fullføring må du kontrollere tabellspørringene, bevisene eller publiseringskvitteringene.
- Avbryt med den opprinnelige runId; bekreft resultatet ut fra den faktiske oppgavetilstanden.
At en run er fullført, er ikke en kvittering for modellpublisering. Publiseringsoppgaver bekreftes fortsatt via den opprinnelige artefaktens status og kildekontroller; QUERY gir ingen implisitt skrive- eller publiseringsrett.
Business Workspace MCP
Spør etter poster basert på publiserte forretningskontrakter, og utfør kommandoer via den opprinnelige ActionPlan.
/mcp/business bruker en egen protected resource og et eget valg av forretningssystem; ontologiens Grant kan ikke gjenbrukes i stedet for forretningsautorisasjon. Forretningssystemet må være publisert, kunne kalles av agenter og oppfylle den opprinnelige sikkerhetspolicyen, og den aktuelle brukeren må ha faktiske kjøretidsroller og -funksjoner.
| Scope | Verktøy | Grenser |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Oppdager bare systemer som omfattes av denne autorisasjonen og som kan kalles nå |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Poster som gjeldende bruker kan lese, og egne planer |
| business-system:plan | dfb_action_plan | Oppretter bare en uforanderlig plan; utfører ingenting |
| business-system:execute | dfb_action_execute | Egen eksplisitt autorisasjon, utføres i henhold til risiko og godkjenning |
- dfb_systems oppdager autoriserte systemer.
- dfb_system_describe leser gjeldende publiseringskontrakt, releaseId og alle hasher, spørringer og kommandoer.
- dfb_query bruker publisert queryKey og angir ved behov objectKey, state, page og pageSize. Det er ikke vilkårlig SQL.
- dfb_record og dfb_work_items leser poster og gjøremål som er tillatt nå.
- Før utførelse bruker du dfb_action_plan og oppgir faktisk releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey og kontraktens payload.
- Kontroller riskClass, requiresApproval og status; bevar expectedRecordVersion når målposter er involvert.
- dfb_action_execute utfører bare planer som gjeldende tilkobling eier og som er klare; godkjenningstokener som kreves ved manuell godkjenning, utstedes av DataFocus.
- Etter feil eller tidsavbrudd brukes dfb_action_status til å gjenopprette den opprinnelige planen; nye forsøk beholder den opprinnelige idempotenssemantikken.
Tilkobling og versjonsbinding
Planen er bundet til den stabile isolasjons-ID-en for gjeldende Grant. Etter at access token er fornyet, kan planer i samme tilkobling fortsatt behandles, og en annen OAuth-tilkobling kan ikke ta den over. Ved utførelse kontrolleres publisert versjon, IR/manifest-hash, versjonen av målposten, planutløp, idempotens og godkjenning på nytt. OAuth-allowlist kan ikke omgå forretningsstyringen.
Inndata for forretningskunnskap og spørsmål som venter på bekreftelse
Registrer forretningsinndata når den tilhørende produksjonsbehandleren er tilgjengelig, og bevar grensen for menneskelig bekreftelse.
De fire verktøyene nedenfor legges til av den offentlige MCP-kontrolleren, avhengig av installerte behandlere og gjeldende scope. De finnes ikke alltid i basiskatalogen. At et Schema er deklarert, betyr ikke at instansen har behandlere, budsjett og rettigheter på plass – du må kontrollere tools/list først.
| Verktøy | Formål | Autorisasjoner eller effekter som ikke oppstår |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registrerer opprinnelig forretningsinndata for et eksisterende arbeidsområde | Genererer ikke bekreftelsesspørsmål, godkjenner ikke, publiserer ikke |
| dfc_ontology_knowledge_input_preview | Midlertidig forhåndsvisning av spørsmålsutkast fra den opprinnelige inndataen | Lagres ikke varig, bekreftes ikke, gir ingen produksjonskvittering |
| dfc_ontology_knowledge_question_submit | Lagrer authored, ubekreftede spørsmål | Slår ikke automatisk sammen svar, gir ikke ansvarsrettigheter eller publiseringsrett |
| dfc_ontology_business_scope_initialize | Initialiserer eksplisitt ett forbrukerscope for et forretningssystem | Publiserer ikke, aktiverer ikke, gir ikke kildetilgang |
Inndata og forhåndsvisning
- Hent workspaceId, workspaceRevision, localRef og preparationDigest fra det faktiske klargjøringsarbeidet.
- propose registrerer forretningsinndata med den opprinnelige input-kontrakten og en stabil idempotencyKey; samme nøkkel kan kun tilsvare samme inndata.
- preview bruker idempotensnøkkelen til den opprinnelige inndataen og ontologyId; den returnerer hver gang serverens revision og et vindu på 60 sekunder, og er ikke en idempotent kvittering for fullført produksjon.
- Når spørsmål skal lagres, bruker question_submit en ny kommandonøkkel, opprinnelig originalInputKey, eksplisitt questionRevision, validFrom, validUntil og expectedRevision; ved opprettelse er expectedRevision null.
Inngang for menneskelig bekreftelse
knowledgeConfirmationPage som returneres av question_submit, er bare en relativ lenke til den opprinnelige innloggingssiden, forhåndsutfylt med et bestemt spørsmål. Den inneholder ikke Bearer-token, åpner ikke siden automatisk og bekrefter ikke kunnskap. QUESTION_STORED_UNCONFIRMED angir uttrykkelig at kunnskapen ennå ikke er bekreftet; svaret må ikke si at «kunnskapen er publisert».
Initialisering av forbrukerscope
business scope initialize krever både publiseringsrett for ontologien og oppretter- eller SourceManager-administrasjonsrett for akkurat dette forretningssystemet. Den bruker faktiske koordinater for domainRid, domainRevisionId og businessSystemId, og klienten kan ikke fylle inn vilkårlige consumerScope-verdier eller bevis på fullføring. Returverdiene INITIALIZED og COMPLETED angir fortsatt uttrykkelig published=false og activationAuthorized=false.
Disse forespørslene gjennomgår også streng validering av JSON, feltsett, bytestørrelse og dybde. Grensen for inndataforespørsler er 1 MiB; enkelte konkrete operasjoner har lavere grenser. Fullstendige inndata- og utdata-Schemaer leveres med verktøyreferansen, og den løsere parameterlogikken i en generell MCP-wrapper kan ikke brukes på disse strenge kontraktene.
Svar, feil og sikre nye forsøk
Tolk feil lag for lag, og bevar oppgavekoordinater og idempotenssemantikk.
| Lag | Hva som kontrolleres | Håndteringsprinsipp |
|---|---|---|
| Nettverk og HTTP | Tilkobling, TLS, 401, 403, 400, 404, 405 osv. | Ikke behandle en mislykket respons som et vanlig spørringsresultat |
| JSON-RPC | error.code, message, data | Skill mellom protokoll-, metode-, parameter- og autorisasjonsproblemer |
| MCP-verktøy | result.isError og structuredContent | HTTP 200 kan likevel være en feil |
| Forretningsresultat | Faktisk status, fullstendighet, feilårsak, nextAction | Mottatt eller klar betyr ikke fullført |
| Kvalifisering som fakta | executionReceipt, citationEligible, contentComplete | Innhold som ikke er kvalifisert, brukes kun til lokalisering eller til å forklare mangler |
Vanlige HTTP-situasjoner
- 401: Bearer mangler eller er ugyldig – forny eller autoriser på nytt i henhold til gjeldende OAuth-flyt.
- 403: Grant, rolle, valgte ressurser, kilderettigheter, Origin eller konfigurasjon oppfyller ikke kravene; ikke prøv å omgå dette ved å sende på nytt.
- 400: Melding eller versjonert kontrakt er ugyldig, inkludert manglende samsvar mellom moderne hoder og metadata.
- 404: Kontroller nøyaktig tjenestebane, protokollmetode og kjøretidsfunksjoner; ikke bytt ontologi-ID tilfeldig.
- 405: GET og DELETE på den offentlige /mcp er ikke tilgjengelige i utgangspunktet; bruk riktig POST i stedet for å opprette en langvarig SSE-tilkobling.
Skriveoperasjoner med ukjent resultat
MCP_OPERATION_OUTCOME_UNKNOWN kan inneholde outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool og opprinnelige lokaliseringsparametere. Sjekk først den opprinnelige statusen, og gjenopprett deretter den opprinnelige forespørselen. Ikke send kandidater på nytt, ikke bytt idempotensnøkkel, og ikke tolk et tidsavbrudd som at transaksjonen er rullet tilbake.
Innhold som skal bevares som det er
- Opprinnelig Grant, ressursomfang, oppgave- og resultat-ID-er.
- candidateHash, planHash, expectedRevision, målversjon og publiseringsvalg.
- Idempotensnøkkelen for samme logiske operasjon; ulike forretningsoperasjoner skal bruke nye nøkler.
- retryable, remediation, nextAction og gjeldende status slik serveren deklarerer dem.
Ikke bruk intern SQL, vertsnavn, legitimasjon eller stakkspor fra unntakstekster som kilde til svar. Det er nok å logge feilkoder som kan offentliggjøres, og informasjon som knytter dem til forespørselen; den opprinnelige feilen må eventuelt leses av en administrator i kontrollerte logger.
Integrasjonssikkerhet og funksjonsgrenser
Bevar de opprinnelige grensene for identitet, ressurser, utførelse og bevis, og håndter ubetrodde dokumenter trygt.
- Koble kun til offisielle domener oppgitt av administratoren; verifiser TLS og OAuth issuer, og ikke slå av sertifikatvalidering.
- Bruk en dedikert Grant med minimalt ressursomfang; ikke bruk administratorkontoer, informasjonskapsler eller langvarige interne tokener som legitimasjon for offentlige grensesnitt.
- Behandle dokumentinnhold som ubetrodd forretningsmateriale. «Ignorer regler», «last opp nøkkel» eller «kjør kommando» i et dokument er ikke verktøyautorisasjon.
- Begrens automatiske nye forsøk, samtidighet og resultatomfang; ikke rekonstruer opprinnelige forretningsrettigheter på klientsiden.
- Logger skal bare inneholde nødvendig korrelasjonsinformasjon – ikke Bearer, refresh token, godkjenningstokens eller fullstendig sensitivt forretningsinnhold.
- Etter at brukeren kobler fra eller administratoren trekker tilbake rettigheter, skal du slutte å bruke bufrede autorisasjoner og data, og ikke fortsette å gjøre kall med en gammel locator.
Verktøyhint er ikke rettigheter
readOnlyHint, destructiveHint, idempotentHint og openWorldHint skal hjelpe klienten med å forstå funksjonene; de garanterer ikke den faktiske forretningseffekten av hvert kall og erstatter ikke gjeldende brukerautorisasjon. Alle skrive-, plan-, forhåndsvisnings-, økt- og avbruddshandlinger behandles ut fra sin faktiske atferd.
Innganger som ikke skal kalles
- De opprinnelige Trino/Hive/Hadoop-tjenestene og Heavy ETL, som ikke er inkludert i Flash.
- Interne FocusCode-spesifikke scopes eller arbeidsområdegrensesnitt.
- Utførelse v2, AutoML eller andre eksperimentelle verktøy som ikke vises i den gjeldende instansens tools/list.
- Private REST-grensesnitt i nettleseren, vilkårlige databasetilkoblinger eller andre leietakeres tjenester for å omgå at MCP avviser forespørselen.
Datasemantikk
Følg serverens kontrakter for eksakte desimaler, typer, valuta, enheter, tid og bevis. Ikke rund av på nytt eller konverter valuta bare fordi utdatateksten ligner et tall, og ikke foreta global rangering av synlige rader når resultatet er avkortet.
Administratoroppsett og betingede brytere
Kontroller faktiske komponenter, offentlige adresser og den opprinnelige rettighetskonfigurasjonen før utvidede funksjoner aktiveres.
| Konfigurasjon | Formål | Krav ved utrulling |
|---|---|---|
| datafocus.mcp.public-base-url | Offisiell ekstern rotadresse | OAuth-oppdagelse, issuer, callback og omvendt proxy samsvarer |
| datafocus.mcp.allowed-origins | Ytterligere godkjente nettleseropphav (Origin) | Konfigureres eksakt; utvides ikke til vilkårlige opphav |
| datafocus.mcp.oauth.route-proof-secret | Dedikert serverhemmelighet for bevis på grafruting | Lagres separat, Bearer brukes ikke som nøkkel |
| datafocus.mcp.analysis.tools.enabled | Interaktive analyseverktøy | Tilhørende data-, kunnskaps- og rettighetstjenester er faktisk tilgjengelige |
| datafocus.mcp.analysis.report-tools.enabled | Vedvarende rapportverktøy | Tilhørende lagring, worker og gjenopprettingskjede er tilgjengelige |
| datafocus.mcp.analysis.apps.enabled | MCP Apps-visning | Klienten deklarerer støtte og kontrollerer returnert _meta |
| datafocus.mcp.authoring.enabled | Utkast- og modelleringskontrakter | Opprinnelige administrator- og ressursrettigheter bevares |
| datafocus.mcp.authoring.apply-enabled | Funksjon for anvendelse av artefakter | Uforanderlige planer, opprinnelige godkjenninger og ny validering av gjeldende status |
| datafocus.mcp.ontology-published-query-enabled | Publiserte modeller og spørringer | Faktisk committed versjon og kildeautorisasjon |
| datafocus.mcp.ontology-candidate-query-enabled | Strukturert kandidatspørring | Eierskap til kandidaten, eksakt versjon og leserettighet |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Autorisasjoner knyttet til delegering av automatisk publisering | Gyldig opprinnelig policy, tillit til offentlige nøkler, budsjett og publiseringsrett |
Disse navnene kommer fra r56-konfigurasjon og implementering; hvorvidt de kan slås på avhenger av tilhørende tjenester og de opprinnelige kontrollpunktene for produksjonssetting. Å bare endre en boolsk verdi legger ikke til manglende behandlere, databaser, valideringsbudsjett eller policyer. Synligheten av utvidelser for kunnskapsinndata og Pi-oppgaver bestemmes av faktisk installerte komponenter.
Kantproxy
Bevar Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name og godkjent Origin. Sett forespørselskropp, tidsavbrudd og TLS i henhold til den faktiske tjenestens krav; ikke videresend den offentlige /mcp til administrasjonsporter eller et annet produkt.
Kontroll før produksjonssetting
- Status for anonym oppdagelse og beskyttede kall er som forventet.
- Vanlige brukere kan bare oppdage sitt autoriserte omfang, og etter at rettigheter er trukket tilbake, avvises påfølgende forespørsler.
- Innebygde Search-økter, SQL, originaltekst og valgfrie rapporter gir hver for seg faktiske resultater.
- Godkjenning av skriving og publisering, samt idempotent gjenoppretting, beholder den opprinnelige atferden.
- Logger og offentlig dokumentasjon inneholder ikke private nøkler, tokener, informasjonskapsler, passord eller interne kundeopplysninger.
Kjørbare klienter og eksempelkall
Verifiser meldinger med den medfølgende minimale klienten uten å omgå OAuth eller gjeldende autorisasjon.
examples/flash_mcp.py er en minimal protokollklient som kun er avhengig av Python-standardbiblioteket. Den logger ikke inn, utfører ikke godkjenninger på vegne av andre, kaller ikke automatisk usynlige verktøy, støtter moderne og eldre protokoller, og avslutter med lagdelt feilhåndtering for HTTP, JSON-RPC og verktøyfeil. Tokenet oppgis via prosessmiljøet og skrives ikke inn i skript eller dokumentasjonsfiler.
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_TOKENLesing og spørring
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.jsonErstatt først plassholdere som ONTOLOGY_ID og TABLE_RESOURCE_ID i forespørselsfilen med faktiske verdier returnert av gjeldende autorisasjon. Klienten nekter å kjøre hvis den finner plassholdere. SQL-eksempelet krever at tilhørende CSV er importert med de opprinnelige kolonnenavnene; uten tilsvarende schema kan det ikke sendes direkte.
Andre scenarier
- Forretningsinngang: bruk --endpoint business og hent en ny Grant for /mcp/business.
- Eldre klienter: velg --protocol 2025-11-25, kjør først initialize, og foreta deretter kall med samme protokoll.
- Innebygd dokumentasjon: bruk resources eller read-resource for å lese den faktiske URI-en.
- Offline selvtest: --self-test verifiserer hvordan moderne hoder og metadata bygges, krever ingen token og sender ingen forespørsler til produktserveren.
Grenser for eksemplet
Klienten er et utgangspunkt for protokollintegrasjon, og genererer ikke automatisk modelleringskandidater, lagrer ikke spørsmål og svar og utfører ingen publisering. Den returnerer den opprinnelige JSON slik at den overordnede agenten kan kontrollere forretningsstatusen; ikke lov brukeren at en spørring, rapport eller publisering er fullført bare ut fra prosessens exit-kode.
Bygg inn ontologidialoggrensesnittet
Bygg inn dialogsiden for mennesker i forretningsfrontenden, og bevar grensene for innlogging og nettlesersikkerhet.
<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 er en eksempel-ID for leietaker og 1001 en eksempel-ID for ontologi; erstatt dem ved bruk med faktiske koordinater du har rettigheter til. En enkelt ontologi kan angis med path eller en støttet query; i all-modus gir @ valg av ontologier den nåværende brukeren har tilgang til. skillId sendes bare videre; ikke påstå ut fra dette at ferdighetsorkestrering kan utføres.
Autentisering og domene
Den innebygde siden er avhengig av en reell DataFocus-innloggingsøkt og sjekker /uc/status. Cross-site-informasjonskapsler, SSO, CSP frame-ancestors og gatewaykonfigurasjon påvirker innebyggingen. Den godtar ikke en MCP Bearer i URL-en som kanal uten innlogging; eksterne outside-lenker som ikke er implementert, kan ikke settes sammen på egen hånd ut fra designforslag.
Forskjellen mellom MCP og iframe
| Metode | Brukes av | Identitet og resultat |
|---|---|---|
| Remote MCP | Eksterne agenter eller tjenesteintegrasjoner | OAuth Grant og strukturerte verktøykvitteringer |
| Ontologidialog i iframe | Menneskelig sluttbruker | Opprinnelig innloggingsøkt og dialoggrensesnitt |
| MCP Apps | MCP-klienter med støtte for utvidelser | Kontrollerte ressurser og gjeldende verktøyresultater, ikke en offentlig erstatning for iframe-innlogging |
Sjekkliste for integrasjonsgodkjenning
Bevis hele forretningskjeden på en faktisk instans; det er ikke nok å bekrefte at grensesnittet returnerer 200.
- Oppdagelse: hent faktisk støttede versjoner, gjeldende verktøykatalog og innebygde ressurser.
- Autorisasjon: vanlige brukere ser kun godkjente ontologier og forretningssystemer; operasjoner uten scope avvises.
- Tabellstruktur: faktiske visningsnavn, kolonner, typer og rettigheter er fullstendige.
- SQL: kontroller av spørringer med én og flere dimensjoner, JOIN, dato, TopN og trunkering samsvarer med den faktiske forretningsdefinisjonen.
- Kunnskap: lokalisering, fullstendig originaltekst og kvalifisering for sitering som fakta samsvarer; blandede spørsmål har samtidig både data- og dokumentgrunnlag.
- Search: modell, init, forslag, resultater, lukking og kontroll av bufferens fullstendighet er bestått.
- Valgfri analyse og rapportering: faktisk tilstand for flere grener, sidebytte, rettighetsendringer og avbrudd beholder den opprinnelige atferden.
- Valgfri modellering: kandidater, planer, opprinnelig godkjenning, faktisk anvendelse og versjonsspørringer kontrolleres fase for fase.
- Forretningshandlinger: publiseringshash, målversjon, godkjenning, idempotens og isolering på tvers av Grant kontrolleres.
- Gjenoppretting: etter tidsavbrudd i nettverket gjenopprettes den opprinnelige tilstanden; etter at kilden er oppdatert, blir gamle lokaliseringer ugyldige og nye spørringer brukes.
Registrering av resultater
Dokumenter instansversjon, brukerrolle, Grant-omfang, konfigurasjonsversjon og faktiske operasjoner med resultater. Protokollklientens offline selvtest, de forventede offline-verdiene for eksempel-CSV-en, statisk JSON Schema-validering og faktisk online funksjonsgodkjenning merkes hver for seg. Ikke ta én bestått fase som bevis for at hele produktet er godkjent.
Spesifikasjonsressurser og vedlikehold
Bruk de fullstendige verktøy-Schemaene som følger med håndboken, og hold dem synkronisert med instansens faktiske oppdagelsesresultater.
| Ressurser | Innhold |
|---|---|
| reference/mcp-tool-catalog.json | Deklarerte inndata-Schemaer for 32 verktøy på ontologisiden og 8 på forretningssiden; enkelte verktøy har også opprinnelige utdata-Schemaer |
| reference/locales.json | 21 valgbare alternativer og 24 kompatible locales samt UI-termer |
| reference/search-keywords.json | Statisk nøkkelordkatalog for 17 eksplisitt angitte locales |
| reference/analysis-contract-manifest.json | Versjonsbegrensninger knyttet til analyse, grener, fakta, kvitteringer og rapporter |
| examples/ | Syntetisk CSV, beskrivelse av forretningsdefinisjoner, topp 3-SQL, forventede resultater og minimal protokollklient |
Innebygde dokumentasjonsressurser
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list og resources/read krever at gjeldende bruker har minst én tilsvarende leserettighet blant metadata, search operate eller etl operate. ETL-dokumentasjonen er en statisk referanse på tvers av produkter; det Flash faktisk kan utføre, er fortsatt begrenset til det Flash eksplisitt rapporterer.
Ekstern protokollreferanse
Som bakgrunn for MCP-protokollen og autorisasjon, se de offisielle spesifikasjonene: https://modelcontextprotocol.io/specification/2026-07-28/basic og https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization.. Endepunkter, verktøy og betinget atferd for dette produktet bestemmes av r56-implementeringen og instansens gjeldende oppdagelsesresultater; generell protokollstøtte kan ikke likestilles med at serveren tilbyr alle valgfrie funksjoner.
Oppgradering og vedlikehold
Ved oppgradering må du oppdage verktøy og versjoner på nytt og sammenligne inndata-Schemaer, utdatakontrakter og konfigurasjon; gamle Grants får ikke automatisk nye scopes. Hold referanser, buffere og kvitteringer bundet til kildeversjonen; etter bekreftede inkompatible endringer skal konteksten hentes på nytt, og gamle lokaliseringer skal ikke tvinges inn i en ny forretningstilstand.
Verktøyparameterreferanse: grunnleggende og innebygd Search
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfc_manual
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| names | array | Valgfritt eller betinget obligatorisk | Eksplisitte navn det skal søkes etter, maksimalt 32 per kall. maxItems: 32 |
| action | string | Valgfritt eller betinget obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: list, read, keywords, functions, etl_requests |
| locale | string | Valgfritt eller betinget obligatorisk | Locale for den eksplisitte statiske referansekatalogen, ikke standardspråket for spørringer. |
| uri | string | Valgfritt eller betinget obligatorisk | URI for en innebygd ressurs som gjeldende verktøy lister opp. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| data | object | Valgfritt eller betinget obligatorisk | Opprinnelig handlingsnyttelast; se funksjonsoppdagelsen og tabellen over handlingsfelter. |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| data | object | Valgfritt eller betinget obligatorisk | Opprinnelig handlingsnyttelast; se funksjonsoppdagelsen og tabellen over handlingsfelter. |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: capabilities |
dfc_ontologies
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| pageSize | integer | Valgfritt eller betinget obligatorisk | Antall elementer per side; følg øvre grense i Schema. minimum: 1; maximum: 100 |
| page | integer | Valgfritt eller betinget obligatorisk | Sidenummer, starter på 1. minimum: 1 |
dfc_ontology_resources
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| resourceTypes | array | Valgfritt eller betinget obligatorisk | Sett av ressurstyper som skal returneres. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| pageSize | integer | Valgfritt eller betinget obligatorisk | Antall elementer per side; følg øvre grense i Schema. minimum: 1; maximum: 100 |
| page | integer | Valgfritt eller betinget obligatorisk | Sidenummer, starter på 1. minimum: 1 |
Verktøyparameterreferanse: tabeller, graf og kunnskap
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfc_ontology_graph
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| relationTypes | array | Valgfritt eller betinget obligatorisk | Relasjonstypefilter. |
| depth | integer | Valgfritt eller betinget obligatorisk | Traverseringsdybde for naboer. minimum: 1; maximum: 3 |
| sourceTypes | array | Valgfritt eller betinget obligatorisk | Kildetypefilter. |
| query | object | Valgfritt eller betinget obligatorisk | Spørringstekst, eller presist versjonert spørringsobjekt tilsvarende action. |
| limit | integer | Valgfritt eller betinget obligatorisk | Øvre grense for antall returnerte resultater. minimum: 1; maximum: 100 |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| nodeKey | string | Valgfritt eller betinget obligatorisk | Nodenøkkel kopiert fra et faktisk grafresultat. |
| keyword | string | Valgfritt eller betinget obligatorisk | Nøkkelord for graflokalisering, ikke syntaks for nøkkelordspørringer. |
| nodeTypes | array | Valgfritt eller betinget obligatorisk | Nodetypefilter. |
dfc_ontology_query
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| routeLocators | array | Valgfritt eller betinget obligatorisk | Fullstendig kopi av den typede rutinglokatoren utstedt av serveren. maxItems: 20 |
| topK | integer | Valgfritt eller betinget obligatorisk | Øvre grense for antall kandidater som hentes; beviser ikke fullstendig dekning. minimum: 1; maximum: 20 |
| queryMode | string | Valgfritt eller betinget obligatorisk | Velg modus for bevisspørring ut fra verktøyets enum. enum: vector, hybrid, graph |
| fanoutPlan | object | Valgfritt eller betinget obligatorisk | Avgrenset søkeplan for grener, i henhold til nestet Schema. |
| structuredPlan | object | Valgfritt eller betinget obligatorisk | Plan for en fullstendig dokumenttabell, bundet til serverens kontrakt; ikke SQL. |
| knowledgeIds | array | Valgfritt eller betinget obligatorisk | Kunnskapsbase-ID fra de faktiske knowledgeBindings. |
| query | string | Obligatorisk | Spørringstekst, eller presist versjonert spørringsobjekt tilsvarende action. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
dfc_knowledge_search
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| topK | integer | Valgfritt eller betinget obligatorisk | Øvre grense for antall kandidater som hentes; beviser ikke fullstendig dekning. minimum: 1; maximum: 20 |
| minScore | number | Valgfritt eller betinget obligatorisk | Laveste samsvarspoeng. minimum: 0; maximum: 1 |
| knowledgeIds | array | Valgfritt eller betinget obligatorisk | Kunnskapsbase-ID fra de faktiske knowledgeBindings. |
| query | string | Obligatorisk | Spørringstekst, eller presist versjonert spørringsobjekt tilsvarende action. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| assetIds | array | Valgfritt eller betinget obligatorisk | Asset-ID for et dokument som er tillatt nå. |
| retrievalStrategy | string | Valgfritt eller betinget obligatorisk | Faktisk støttet søkestrategi. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| qdrantId | string / integer | Valgfritt eller betinget obligatorisk | Indeksidentifikator returnert av den faktiske lokaliseringen. |
| pageNo | integer | Valgfritt eller betinget obligatorisk | Faktisk dokumentside eller sidenummer i sideinndelingen. |
| evidenceId | string | Valgfritt eller betinget obligatorisk | Bevis-ID returnert av samme kunnskapslokalisering. |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: chunk, document, page_context |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| documentId | string / integer | Valgfritt eller betinget obligatorisk | Dokument-ID fra samme lokalisering. |
| radius | integer | Valgfritt eller betinget obligatorisk | Antall tilstøtende sider som tas med. minimum: 0; maximum: 3 |
| chunkId | string | Valgfritt eller betinget obligatorisk | Faktisk chunk-ID fra samme lokalisering. |
dfc_table
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| maxRows | integer | Valgfritt eller betinget obligatorisk | Øvre grense for antall returnerte rader; ikke et rangeringsomfang for klienten. minimum: 1; maximum: 200 |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: detail, query |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| id | string | Valgfritt eller betinget obligatorisk | Faktisk tabellressurs-ID, ikke fysisk navn eller visningsnavn. |
| sql | string | Valgfritt eller betinget obligatorisk | Én enkelt skrivebeskyttet Doris SQL-setning innenfor ontologiens omfang, med eksplisitte utdatakolonner. |
Verktøyparameterreferanse: analyse og rapporter
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfc_analysis_ask
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| question | string | Obligatorisk | Naturspråklig spørsmål eller kompatibelt oppfølgingsspørsmål. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| language | string | Valgfritt eller betinget obligatorisk | Eksplisitt locale for svar eller spørring; hva som skjer hvis den utelates, følger reglene for det aktuelle verktøyet. |
| sessionId | string | Valgfritt eller betinget obligatorisk | Faktisk øktlokator under samme Grant. |
dfc_analysis_refine
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| branchId | string | Valgfritt eller betinget obligatorisk | Strukturert grenlokator utstedt av serveren. |
| resultId | string | Obligatorisk | Lokator for det opprinnelig returnerte analyseresultatet. |
| question | string | Valgfritt eller betinget obligatorisk | Naturspråklig spørsmål eller kompatibelt oppfølgingsspørsmål. |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| change | object | Valgfritt eller betinget obligatorisk | Naturspråklig endring eller typet filter_patch. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| language | string | Valgfritt eller betinget obligatorisk | Eksplisitt locale for svar eller spørring; hva som skjer hvis den utelates, følger reglene for det aktuelle verktøyet. |
| sessionId | string | Obligatorisk | Faktisk øktlokator under samme Grant. |
| expectedRevision | integer | Obligatorisk | Forutsatt versjon av det opprinnelige resultatet eller forretningshodet; kan være null når et spørsmål opprettes. minimum: 1 |
| visualId | string | Valgfritt eller betinget obligatorisk | Visualiseringslokator bundet til grenen. |
dfc_analysis_page
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| branchId | string | Obligatorisk | Strukturert grenlokator utstedt av serveren. |
| resultId | string | Obligatorisk | Lokator for det opprinnelig returnerte analyseresultatet. |
| pageNo | integer | Obligatorisk | Faktisk dokumentside eller sidenummer i sideinndelingen. minimum: 1; maximum: 10000 |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| pageSize | integer | Obligatorisk | Antall elementer per side; følg øvre grense i Schema. minimum: 1; maximum: 100 |
| sessionId | string | Obligatorisk | Faktisk øktlokator under samme Grant. |
| expectedRevision | integer | Obligatorisk | Forutsatt versjon av det opprinnelige resultatet eller forretningshodet; kan være null når et spørsmål opprettes. minimum: 1 |
dfc_analysis_result_get
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| resultId | string | Obligatorisk | Lokator for det opprinnelig returnerte analyseresultatet. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| sessionId | string | Obligatorisk | Faktisk øktlokator under samme Grant. |
dfc_analysis_cancel
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| resultId | string | Obligatorisk | Lokator for det opprinnelig returnerte analyseresultatet. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| sessionId | string | Obligatorisk | Faktisk øktlokator under samme Grant. |
dfc_analysis_close
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| sessionId | string | Obligatorisk | Faktisk øktlokator under samme Grant. |
dfc_report_create
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| goal | string | Obligatorisk | Analysemålet for rapporten. |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| language | string | Valgfritt eller betinget obligatorisk | Eksplisitt locale for svar eller spørring; hva som skjer hvis den utelates, følger reglene for det aktuelle verktøyet. |
| title | string | Valgfritt eller betinget obligatorisk | Valgfri rapporttittel. |
dfc_report_status
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| reportId | string | Obligatorisk | Vedvarende rapportlokator under gjeldende Grant. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
dfc_report_cancel
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| reportId | string | Obligatorisk | Vedvarende rapportlokator under gjeldende Grant. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
Verktøyparameterreferanse: modellering og opprinnelige oppgaver
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfc_ontology_agent
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| mode | string | Valgfritt eller betinget obligatorisk | QUERY eller AUTHORING; funksjonene autoriseres hver for seg. enum: QUERY, AUTHORING |
| instruction | string | Valgfritt eller betinget obligatorisk | Brukerens behovstekst; må være lik i kontekst og innsending. maxLength: 16000 |
| idempotencyKey | string | Valgfritt eller betinget obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. maxLength: 128 |
| action | string | Obligatorisk | Handlingsnavn. Brukes i henhold til gjeldende enum og parameterne for den aktuelle handlingen. enum: start, status, cancel |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| runId | string | Valgfritt eller betinget obligatorisk | Opprinnelig oppgave-ID for samme ontologi og Grant. |
| contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
Rotobjektet for inndata til dette verktøyet har ingen felter; bruk et tomt arguments-objekt.
dfc_artifact_context
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Valgfritt eller betinget obligatorisk | Ressursomfangstypen i den faktiske artefaktkontrakten. |
| ontologyId | string | Valgfritt eller betinget obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| projectId | string | Valgfritt eller betinget obligatorisk | Prosjekt-ID innenfor gjeldende autorisasjon. |
| artifactId | string | Valgfritt eller betinget obligatorisk | Faktisk ID for den eksisterende artefakten som skal redigeres. |
| instruction | string | Obligatorisk | Brukerens behovstekst; må være lik i kontekst og innsending. |
| variables | object | Valgfritt eller betinget obligatorisk | Variabelobjekt som oppgis i henhold til den returnerte kontrakten. |
| previewInput | object | Valgfritt eller betinget obligatorisk | Avgrenset inndata for forhåndsvisning, oppgitt i henhold til kontrakten. |
| viewport | object | Valgfritt eller betinget obligatorisk | Visningsområdet (viewport) som den opprinnelige kontrakten krever. |
dfc_ontology_table_schema
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| sourceAssetRef | string | Obligatorisk | Registrert referanse til en strukturert ressurs (asset), for eksempel table:123. |
| fields | array | Obligatorisk | Feltene i gjeldende kilde med valgfrie eksplisitte typedeklarasjoner. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| proposalId | string | Obligatorisk | Opprinnelig kandidat-ID opprettet av gjeldende Grant. |
| candidateHash | string | Obligatorisk | Eksakt hash for den opprinnelige kandidaten på serveren. |
| previewInput | object | Obligatorisk | Avgrenset inndata for forhåndsvisning, oppgitt i henhold til kontrakten. |
dfc_artifact_status
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| proposalId | string | Valgfritt eller betinget obligatorisk | Opprinnelig kandidat-ID opprettet av gjeldende Grant. |
| planId | string | Valgfritt eller betinget obligatorisk | Uforanderlig ID for anvendelsesplanen. |
dfc_artifact_plan
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| proposalId | string | Obligatorisk | Opprinnelig kandidat-ID opprettet av gjeldende Grant. |
| candidateHash | string | Obligatorisk | Eksakt hash for den opprinnelige kandidaten på serveren. |
| expectedTargetVersion | integer | Obligatorisk | Forutsatt gjeldende, faktisk målversjon. minimum: 0 |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
dfc_artifact_apply
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| planId | string | Obligatorisk | Uforanderlig ID for anvendelsesplanen. |
| planHash | string | Obligatorisk | Hashen som ble returnert av den opprinnelige planen. |
| approvalToken | string | Obligatorisk | Godkjenningsmateriale utstedt av serveren; det er forbudt å generere det selv. |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
dfc_artifact_submit
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| Alternativ 1 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Alternativ 1 / scopeType | string | Valgfritt eller betinget obligatorisk | Ressursomfangstypen i den faktiske artefaktkontrakten. |
| Alternativ 1 / ontologyId | string | Valgfritt eller betinget obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| Alternativ 1 / projectId | string | Valgfritt eller betinget obligatorisk | Prosjekt-ID innenfor gjeldende autorisasjon. |
| Alternativ 1 / artifactId | string | Valgfritt eller betinget obligatorisk | Faktisk ID for den eksisterende artefakten som skal redigeres. |
| Alternativ 1 / instruction | string | Obligatorisk | Brukerens behovstekst; må være lik i kontekst og innsending. |
| Alternativ 1 / variables | object | Valgfritt eller betinget obligatorisk | Variabelobjekt som oppgis i henhold til den returnerte kontrakten. |
| Alternativ 1 / previewInput | object | Valgfritt eller betinget obligatorisk | Avgrenset inndata for forhåndsvisning, oppgitt i henhold til kontrakten. |
| Alternativ 1 / viewport | object | Valgfritt eller betinget obligatorisk | Visningsområdet (viewport) som den opprinnelige kontrakten krever. |
| Alternativ 1 / contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. |
| Alternativ 1 / contextHash | string | Obligatorisk | Fullstendig konteksthash returnert av context. |
| Alternativ 1 / baseArtifactHash | string | Obligatorisk | Hash for basisartefakten returnert av context. |
| Alternativ 1 / baseArtifactVersion | integer | Obligatorisk | Basisversjonen returnert av context. minimum: 0 |
| Alternativ 1 / candidate | object | Obligatorisk | Kandidatobjektet som samsvarer med den gjeldende returnerte kontrakten. |
| Alternativ 1 / clientRequestId | string | Obligatorisk | Klientens idempotensnøkkel, brukt stabilt for gjeldende kandidatforespørsel. |
| Alternativ 2 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: ONTOLOGY_RELEASE |
| Alternativ 2 / contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. 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 |
| Alternativ 2 / ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| Alternativ 2 / candidateHash | string | Obligatorisk | Eksakt hash for den opprinnelige kandidaten på serveren. |
| Alternativ 2 / workspaceId | string | Obligatorisk | Faktiske arbeidsområdekoordinater for kandidaten. |
| Alternativ 2 / workspaceRevision | string | Obligatorisk | Nøyaktig kandidatversjon; ikke bruk latest. |
| Alternativ 2 / releases | object | Obligatorisk | Eksakt versjonsvalg, oppgitt i henhold til kontrakten for ontologipublisering. |
| Alternativ 2 / selection | object | Obligatorisk | Oppgir bare eksplisitte koordinater for forretningsvalg; inneholder ikke rettigheter eller fullføringsbevis. |
| Alternativ 2 / idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| Alternativ 3 / Alternativ 1 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: ONTOLOGY_RELEASE |
| Alternativ 3 / Alternativ 1 / contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. enum: ontology-workspace-create-mcp-submit-v1 |
| Alternativ 3 / Alternativ 1 / ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| Alternativ 3 / Alternativ 1 / workspaceId | string | Obligatorisk | Faktiske arbeidsområdekoordinater for kandidaten. |
| Alternativ 3 / Alternativ 1 / resources | array | Obligatorisk | Opprinnelige modelldeklarasjoner som serveren kompilerer. minItems: 1 |
| Alternativ 3 / Alternativ 1 / idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| Alternativ 3 / Alternativ 2 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: ONTOLOGY_RELEASE |
| Alternativ 3 / Alternativ 2 / contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. enum: ontology-workspace-create-mcp-submit-v2 |
| Alternativ 3 / Alternativ 2 / ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| Alternativ 3 / Alternativ 2 / workspaceId | string | Obligatorisk | Faktiske arbeidsområdekoordinater for kandidaten. |
| Alternativ 3 / Alternativ 2 / resources | array | Obligatorisk | Opprinnelige modelldeklarasjoner som serveren kompilerer. minItems: 1 |
| Alternativ 3 / Alternativ 2 / idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| Alternativ 3 / Alternativ 2 / releaseSelections | object | Obligatorisk | Den nøyaktige releaseId for hver publiserte referanse og dens avhengighetslukking. |
| Alternativ 4 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliseringstype som faktisk er aktivert. enum: ONTOLOGY_RELEASE |
| Alternativ 4 / contractVersion | string | Obligatorisk | Du må bruke den eksakte kontraktversjonen som faktisk støttes. enum: ontology-initial-activation-retirement-submit-v1 |
| Alternativ 4 / ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| Alternativ 4 / domainRid | string | Obligatorisk | Faktisk RID for forretningsdomenet. |
| Alternativ 4 / consumerScopes | array | Obligatorisk | Eksakte forbrukerscopes som serveren tillater. minItems: 1; maxItems: 256 |
| Alternativ 4 / idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
Verktøyparameterreferanse: kunnskapsinndata og omfang
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfc_ontology_knowledge_input_propose
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| request | object | Obligatorisk | Opprinnelig forespørsel om forretningsinndata; i henhold til det fullstendige nestede Schemaet. |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. minLength: 1; maxLength: 128 |
Dette verktøyet har i tillegg et eget outputSchema. Kontroller fullstendighet, status og autorisasjonsfelter som eksplisitt er false i utdataene, og ikke tolk resultatet som mer fullført enn det er.
dfc_ontology_knowledge_input_preview
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. minLength: 1; maxLength: 128 |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
Dette verktøyet har i tillegg et eget outputSchema. Kontroller fullstendighet, status og autorisasjonsfelter som eksplisitt er false i utdataene, og ikke tolk resultatet som mer fullført enn det er.
dfc_ontology_knowledge_question_submit
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| questionRevision | $ref | Obligatorisk | Eksplisitt versjon av spørsmålet som venter på bekreftelse. |
| idempotencyKey | $ref | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. |
| originalInputKey | $ref | Obligatorisk | Idempotensnøkkelen som tilsvarer den opprinnelige kunnskapsinndataen. |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. |
| validUntil | $ref | Obligatorisk | Slutten på spørsmålets gyldighetsvindu, i UTC-tid. |
| expectedRevision | oneOf | Obligatorisk | Forutsatt versjon av det opprinnelige resultatet eller forretningshodet; kan være null når et spørsmål opprettes. |
| validFrom | $ref | Obligatorisk | Starten på spørsmålets gyldighetsvindu, i UTC-tid. |
Dette verktøyet har i tillegg et eget outputSchema. Kontroller fullstendighet, status og autorisasjonsfelter som eksplisitt er false i utdataene, og ikke tolk resultatet som mer fullført enn det er.
dfc_ontology_business_scope_initialize
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| domainRevisionId | string | Obligatorisk | Eksakt versjon av forretningsdomenet. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Obligatorisk | Idempotensnøkkel som gjenbrukes stabilt for samme logiske operasjon. minLength: 1; maxLength: 128 |
| businessSystemId | string | Obligatorisk | Faktisk forretningssystem-ID. minLength: 1 |
| ontologyId | string | Obligatorisk | Faktisk ontologi-ID innenfor denne autorisasjonen, beholdt som streng. minLength: 1 |
| domainRid | string | Obligatorisk | Faktisk RID for forretningsdomenet. minLength: 1; maxLength: 128 |
Dette verktøyet har i tillegg et eget outputSchema. Kontroller fullstendighet, status og autorisasjonsfelter som eksplisitt er false i utdataene, og ikke tolk resultatet som mer fullført enn det er.
Verktøyparameterreferanse: Business Workspace
Fullstendige navn og inndatafelter, gruppert per verktøy for oppslag.
Tabellene nedenfor er en oppslagsreferanse for inndatafeltene til de gjeldende r56-verktøyene. Fullstendige nestede typer, oneOf, betingede obligatoriske felter, mønsterbegrensninger og enkelte utdata-Schemaer finnes i reference/mcp-tool-catalog.json; før endelig innsending må du fortsatt lese tools/list for gjeldende Grant. «Valgfritt» i tabellene fjerner ikke kravene til intern validering i handlingen.
dfb_systems
Rotobjektet for inndata til dette verktøyet har ingen felter; bruk et tomt arguments-objekt.
dfb_system_describe
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillates av gjeldende forretnings-Grant. |
dfb_query
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillates av gjeldende forretnings-Grant. |
| queryKey | string | Obligatorisk | Den publiserte spørringsnøkkelen som returneres av describe. |
| objectKey | string | Valgfritt eller betinget obligatorisk | Nøkkelen til det publiserte objektet. |
| pageSize | integer | Valgfritt eller betinget obligatorisk | Antall elementer per side; følg øvre grense i Schema. minimum: 1; maximum: 100 |
| page | integer | Valgfritt eller betinget obligatorisk | Sidenummer, starter på 1. minimum: 1 |
| state | string | Valgfritt eller betinget obligatorisk | Filter for forretningsstatus eller serverstatus. |
dfb_record
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| recordId | string / integer | Obligatorisk | ID for en forretningspost som det for øyeblikket er tillatt å lese. |
| systemId | string / integer | Obligatorisk | System-ID som tillates av gjeldende forretnings-Grant. |
dfb_work_items
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillates av gjeldende forretnings-Grant. |
dfb_action_plan
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| expectedRecordVersion | integer | Valgfritt eller betinget obligatorisk | Gjeldende versjon for optimistisk låsing av målposten. minimum: 1 |
| systemId | string / integer | Obligatorisk | System-ID som tillates av gjeldende forretnings-Grant. |
| commandType | string | Obligatorisk | Kommandotypen i den publiserte kontrakten. |
| canonicalIrHash | string | Obligatorisk | Hashen til den kanoniske IR-en i den gjeldende publiseringen. |
| releaseId | string / integer | Obligatorisk | Faktisk versjons-ID for publiseringskontrakten. |
| payload | object | Obligatorisk | Nyttelast som samsvarer med den gjeldende kommandokontrakten i describe. |
| releaseHash | string | Obligatorisk | Hashen til den faktiske publiseringskontrakten. |
| targetRecordId | string / integer | Valgfritt eller betinget obligatorisk | Den faktiske målposten som operasjonen gjelder. |
| agentManifestHash | string | Obligatorisk | Hash for agentens faktiske funksjonsmanifest (manifest). |
| planIdempotencyKey | string | Obligatorisk | Stabil idempotensnøkkel for forretningsplanen. |
dfb_action_status
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| actionPlanId | string / integer | Obligatorisk | Handlingsplan-ID som eies av gjeldende forretnings-Grant. |
dfb_action_execute
| Parameter | Type | Krav | Betydning og omfang |
|---|---|---|---|
| approvalToken | string | Valgfritt eller betinget obligatorisk | Godkjenningsmateriale utstedt av serveren; det er forbudt å generere det selv. |
| actionPlanId | string / integer | Obligatorisk | Handlingsplan-ID som eies av gjeldende forretnings-Grant. |