OT Flash Agent- och MCP-integrationsmanual
Protokoll, auktorisering, verktygskontrakt och fullständigt anropsflöde
Använd den offentliga Remote MCP i OT Flash r56 för att bygga spårbara data- och kunskapsapplikationer. Manualen beskriver OAuth, protokollmeddelanden, en parameterreferens för alla deklarerade verktyg, bevisregler, villkorade funktioner och återställningsflöden, och innehåller körbara klienter samt exempel med syntetiska data.
Agentutvecklare, integrationsingenjörer och administratörer
De medföljande exemplen behåller kinesiska visningsnamn för fälten. Översättningen av gränssnittsspråket och den förklarande texten ändrar inte de faktiska tabellnamnen, kolumnnamnen, enumvärdena, verktygsnamnen eller protokollfälten.
Innehållsförteckning
- 1Omfång och slutförandekriterier för agentintegration
- 2Snabb anslutning och funktionsidentifiering
- 3OAuth-discovery, registrering och auktorisering
- 4Scope, resursgränser och realtidsbehörigheter
- 5HTTP- och moderna MCP-meddelanden
- 6Kompatibilitet med äldre protokollklienter
- 7Välj rätt verktyg och beviskanal
- 8Ontologiresurser och ID-typer
- 9Doris-tabellfrågor och strukturkontrakt
- 10Flerdimensionell Top3 och trunkeringshantering
- 11Kunskapssökning, fullständig originaltext och bevisgiltighet
- 12Inbyggd Search-modell och session
- 13Språk och regionala konventioner
- 14Kombinerad analys och interaktiva resultat
- 15Beständiga visualiseringsrapporter och MCP Apps
- 16Artefaktutkast, förhandsvisning, plan och tillämpning
- 17Skapande av ontologikandidater och publiceringskontrakt
- 18Publicerad modell, kandidatfrågor och referenshölje
- 19Delegerade uppgifter för ontologiagenten
- 20MCP för affärsarbetsytan
- 21Inmatning av affärskunskap och frågor som väntar på bekräftelse
- 22Svar, fel och säkra återförsök
- 23Integrationssäkerhet och funktionsgränser
- 24Administratörskonfiguration och villkorade funktionsflaggor
- 25Körbara klienter och anropsexempel
- 26Bädda in ontologins dialoggränssnitt
- 27Checklista för integrationsgodkännande
- 28Referensresurser och underhåll
- 29Referens för verktygsparametrar: grundläggande verktyg och inbyggd Search
- 30Referens för verktygsparametrar: tabeller, graf och kunskap
- 31Referens för verktygsparametrar: analys och rapportering
- 32Referens för verktygsparametrar: modellering och agentuppgifter
- 33Referens för verktygsparametrar: kunskapsinmatning och omfång
- 34Referens för verktygsparametrar: affärsarbetsytan
Omfång och slutförandekriterier för agentintegration
Välj ingång för auktoriseringen och slutför frågor, bevisinhämtning eller kontrollerade skrivningar utifrån serverns kvitton.
OT Flash r56 erbjuder externa agenter data- och kunskapsförmågor inom ontologins omfång via Remote MCP, samt en separat ingång till affärsarbetsytan. En agent ska utgå från den faktiska tools/list, inputSchema, OAuth-scope och de aktuella resursbehörigheterna för att avgöra vad som kan utföras, och får inte utifrån en statisk manual anta att en driftsättning har alla valfria funktioner aktiverade.
| Ingång | Syfte | Avgränsning |
|---|---|---|
| /mcp | Ontologi, datatabeller, dokumentkunskap, inbyggd Search samt villkorligt tillgänglig analys och modellering | Snittet mellan den aktuella användarens behörigheter och de resurser som omfattas av den här auktoriseringen |
| /mcp/business | Identifiering av affärssystem, frågor, åtgärdsplaner, status och exekvering | Separat auktorisering per affärssystem samt publicerade kontrakt |
| Inbäddad sida för ontologiagent | Ontologidialog i det mänskliga gränssnittet | Kräver en verklig inloggningssession och är inte en ingång för MCP-tokenutbyte utan inloggning |
Funktionsklassificering
- Grundläggande läsning: ontologi och resurser, graflokalisering, kunskapssökning och fullständig originaltext, detaljer om auktoriserade tabeller samt Doris SQL.
- Separat delegering: dfc_search kräver search:operate och fortsätter använda den ursprungliga användarens och modellens behörigheter.
- Villkorligt tillgängligt: analys, beständiga rapporter, artefaktutkast och tillämpning av dem, frågor mot ontologimodeller samt delegerade agentuppgifter.
- Otillgängliga funktioner: Flashs dfc_etl rapporterar endast capabilities och tillhandahåller ingen ETL-exekvering motsvarande Heavy. AutoML och ingångar till den interna FocusCode-arbetsytan ingår inte i det offentliga Flash-API som beskrivs i den här manualen.
Kriterier för slutförande
Läsning av fakta kräver ett faktiskt användbart kvitto från en fråga eller en fullständig originaltext; för genererade kandidater måste det anges att de ännu inte har tillämpats; publicering kräver ett verkligt APPLIED-kvitto; vid avbrytande måste begäran och bekräftelse hållas isär. Svarstext, HTTP 200, att verktyget har tagit emot anropet eller att modellen beskriver något som ”slutfört” kan inte var för sig bevisa att en affärsåtgärd har lyckats.
Det medföljande reference/mcp-tool-catalog.json är en offlinereferens över de deklarationer som finns i r56. Den innehåller även villkorligt aktiverade definitioner och är inte någon användares aktuella tools/list. Den fullständiga katalogen omfattar 28 kärnverktyg för ontologi, 4 villkorade tillägg från kontrollern samt 8 verktyg på affärssidan, vilket inte innebär att alla är tillgängliga som standard.
Snabb anslutning och funktionsidentifiering
Börja med instansens officiella domän och identifiera faktiskt tillgängliga verktyg med minsta möjliga behörighet.
- Be administratören om den officiella HTTPS-rotadressen och om vilka ontologier eller affärssystem som ska nås. Använd inte dokumentationens exempeldomäner för anrop mot verkliga affärssystem.
- Konfigurera MCP-serveradressen som https://flash.example.com/mcp; affärsarbetsytan använder /mcp/business på samma domän.
- Starta OAuth-inloggning och auktorisering på det sätt som klienten stöder och kontrollera resurser och scope; skicka inte användarnamn och lösenord till MCP.
- Använd discovery eller initiering enligt den protokollgeneration som klienten använder och läs sedan tools/list och resursbeskrivningarna.
- Gör först en liten skrivskyddad förfrågan, kontrollera strukturerade resultat och fel, och genomför först därefter användarens uppgift.
Konfigurationsutdrag för klienten
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Utdraget visar hur serveradressen är tänkt att konfigureras; konfigurationsfilens exakta struktur och OAuth-stödet beror på klienten. Ange aldrig verkliga access_token, refresh_token, cookies eller administratörslösenord i offentliga filer.
Discovery i det moderna protokollet
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": {}
}
}
}Kontroller före anslutning
- Resursens rotadress, OAuth-issuer och den omvända proxyns externa adress stämmer överens.
- Klienten stöder rätt protokollgeneration i stället för att alltid skicka initialize till ingången för det nya protokollet.
- Aktuell auktorisering är kopplad till den ontologi eller det affärssystem som behövs.
- Token är giltig och nya valfria scope har uttryckligen beviljats.
OAuth-discovery, registrering och auktorisering
Använd auktoriseringskod och PKCE; exponera inte produktens inloggningsuppgifter för agenten.
| Slutpunkt | Metod | Syfte |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Discovery av ontologins MCP-resurs |
| /.well-known/oauth-protected-resource/mcp | GET | Kompatibel discovery via ontologiresursens sökväg |
| /.well-known/oauth-protected-resource/mcp/business | GET | Discovery av affärs-MCP-resursen |
| /.well-known/oauth-authorization-server | GET | Metadata för auktoriseringsservern |
| /oauth/register | POST JSON | Dynamisk registrering av public client |
| /oauth/authorize | GET- eller POST-formulär | Inloggning, resursval och bekräftelse av auktorisering |
| /oauth/token | POST-formulär | Inlösen av auktoriseringskod och rotation av refresh-token |
| /oauth/revoke | POST-formulär | Återkallelse av token |
| /oauth/grants | GET | Inloggade användare kan visa auktoriserade anslutningar |
| /oauth/grants/revoke | POST-formulär | Återkalla anslutning via den ursprungliga sidans flöde |
Steg i auktoriseringen
- Läs metadata för skyddade resurser och auktoriseringsservern. Ett 401-svar med WWW-Authenticate på en förfrågan utan token pekar på adressen för resursdiscovery.
- Registrera eller använd klientidentitet. r56:s dynamiska registrering av public client använder token_endpoint_auth_method=none; en klienthemlighet kan inte ersätta PKCE.
- Generera slumpmässig state och code_verifier samt beräkna S256 code_challenge.
- Öppna authorize-adressen som anges i metadata och skicka response_type=code, client_id, exakt redirect_uri, scope, resource, state, code_challenge och code_challenge_method=S256.
- Användaren loggar in i DataFocus och väljer ontologi eller affärssystem. Klienten får inte i förväg välja resurser som användaren saknar åtkomst till.
- Ta emot återanropet, verifiera state och issuer och lös in auktoriseringskoden med den ursprungliga code_verifier.
- Använd endast access_token för MCP Bearer-autentisering. Förnya via det ursprungliga OAuth-flödet och spara den roterade refresh_token på ett säkert sätt.
Registreringsexempel
{
"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"]
}Webbklienters återanropsadress använder HTTPS; native-klienter kan använda loopback-adresser som stöds. Både auktorisering och tokeninlösen kräver exakt matchning mot den registrerade återanropsadressen. Ett Grant gäller en enda skyddad resurs (protected resource); blanda inte ontologins scope och affärsarbetsytans scope i samma anslutning.
Tokens livscykel
I r56 har servern som standard en livslängd på 3 600 sekunder för access token, 2 592 000 sekunder för refresh token och 300 sekunder för auktoriseringskoder; en driftsättning kan åsidosätta dessa värden. Klienten ska avgöra utifrån expires_in i tokensvaret och faktiska fel, och inte hårdkoda standardvärdena. Byt till de nya tokens efter förnyelse. Om en roll, en resursbehörighet eller ett Grant återkallas nekas efterföljande anrop.
Scope, resursgränser och realtidsbehörigheter
Auktoriseringens scope delegerar befintliga behörigheter, ger ingen rolluppgradering och delar inte affärsstatus mellan olika Grant.
| Scope | Typiska funktioner | Viktiga begränsningar |
|---|---|---|
| ontology.metadata:read | Ontologi, resurser och tabellstruktur | Ontologin och tabellerna måste ingå i auktoriseringen och vara läsbara för användaren just nu |
| ontology.graph:read | Grafsökning och grannoder | Returnerar lokaliseringsinformation, inte faktabevis |
| ontology.knowledge:read | Kunskapslokalisering och fullständig originaltext | Behåller kunskapsbibliotekets och dokumentens ursprungliga behörigheter |
| ontology.table:query | SQL mot ontologitabeller samt frågor mot publicerade modeller | Tabellfrågor kräver även metadata-scope; behörigheter för de faktiska källorna och kolumnerna gäller fortfarande |
| search:operate | Inbyggd nyckelordsmodell och sessioner | Separat, uttrycklig delegering; körs med den ursprungliga modellens behörigheter och användarens tabell- och kolumnbehörigheter |
| etl:operate | ETL-capabilities i Flash | Ger ingen åtkomst till Heavy ETL |
| authoring.contract:read | Villkorligt tillgängliga modelleringskontrakt | Kräver även funktionsflagga och berörda resurser |
| authoring.artifact:read | Läsning av kandidater, planer m.m. inom den aktuella auktoriseringen | Bundet till den ursprungliga huvudmannens Grant och resurser |
| authoring.artifact:draft | Inskickning av kandidater, förhandsvisning m.m. | Ger inte behörighet till exekvering eller publicering |
| authoring.artifact:apply | Kontrollerade planer och tillämpning | Kräver fortfarande den ursprungliga affärsrollen, policyer och godkännande |
| execution.script:draft | Utkast till vissa skript | Ger inte behörighet till faktisk skriptexekvering |
| datasource.http:read / draft / test / import | Villkorligt tillgängliga artefaktfunktioner för HTTP-datakällor | Separat funktionsflagga och ursprunglig behörighet för varje funktion |
Kombinerade krav för läsning
dfc_table-detail kräver ontology.metadata:read; query kräver dessutom ontology.table:query. dfc_ontology_query kräver båda läs-scopen graph och knowledge. dfc_knowledge_search/detail kräver knowledge. published_model/published_query går via table:query; candidate_query kräver dessutom authoring.artifact:read. Analysverktygen kontrollerar även vilka bevis-scope som är tillåtna; beständiga rapporter kräver metadata och table query.
Hårdkoda inte standardauktorisering
I r56 ingår table query i ontologins standarduppsättning av scope; Search och ETL kräver uttrycklig delegering. I slutändan avgör discovery-metadata, auktoriseringssidan, tokens faktiska scope och tools/list. Påståenden i äldre dokumentation om att ”ontologin som standard aldrig har SQL” eller att det finns ”endast sex verktyg” kan inte användas som underlag för den nuvarande implementationen.
Isolering av tillstånd
Sessioner, rapporter, kandidater och åtgärdsplaner har var sin ägare och sitt eget omfång. När en access token förnyas överförs inte arbete som hör till det ursprungliga Grant till ett annat Grant. Slå inte ihop sessionId, reportId, planId, godkännandetokens eller källtokens som returnerats av en annan anslutning med den aktuella anslutningen.
HTTP- och moderna MCP-meddelanden
Skicka korrekt metadata för varje förfrågan och matchande routinghuvuden, och hantera HTTP-svar och verktygsresultat var för sig.
| Område | r56-beteende |
|---|---|
| Transport | Tillståndslös Streamable HTTP, POST JSON-RPC |
| Versioner som stöds | 2026-07-28 samt 2025-11-25, 2025-06-18 och 2025-03-26 |
| Moderna metoder | server/discover tools/list tools/call resources/list resources/read, tillgängliga enligt de faktiska funktionerna |
| Sessionshuvud | Inget Mcp-Session-Id tilldelas |
| GET och DELETE | /mcp och /mcp/business returnerar 405 |
| SSE-notifieringar från servern | Tillhandahålls inte av dessa två offentliga MCP-ingångar |
| Katalogcache | Modern discovery och listning returnerar ttlMs=60000 och cacheScope=private |
| Vanliga resultat | Moderna resultat innehåller resultType=complete samt metadata om tjänsteidentitet |
Innehåll som måste matcha
- MCP-Protocol-Version stämmer överens med io.modelcontextprotocol/protocolVersion i params._meta.
- Mcp-Method stämmer överens med JSON-RPC-metoden.
- Mcp-Name för tools/call stämmer överens med params.name; namnhuvudet för resources/read stämmer överens med URI:n.
- Varje modern förfrågan innehåller io.modelcontextprotocol/clientCapabilities-objektet; ange även standardfältet clientInfo så att klienten kan identifieras.
Anropsexempel
{
"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": {}
}
}
}Motsvarande HTTP-huvuden är Mcp-Method: tools/call och Mcp-Name: dfc_ontologies. Samtliga ACCESS_TOKEN i exemplen är platshållare. Lägg aldrig en Bearer-token i URL:er, JSON-parametrar eller cachenycklar.
Läsning av resultat
Hantera först HTTP-statusen och kontrollera därefter JSON-RPC error; finns ett result fortsätter du med att kontrollera isError. Lyckade verktygsresultat tillhandahåller vanligen structuredContent samt textinnehåll som innehåller samma affärs-JSON; läs i första hand den strukturerade kanalen och räkna inte text och structuredContent som två oberoende fakta när du sammanställer. HTTP 200 kan innehålla verktygsfel.
Offentliga resurser och UI
De inbyggda beskrivningsresurserna är inte beroende av MCP Apps. Ingången till affärsarbetsytan får därmed inte tillgång till ontologibeskrivningsresurserna. Klienter som stöder visualisering bör hitta motsvarande UI via de faktiska funktionerna och verktygets _meta och inte gissa resurs-URI:er som inte har returnerats.
Kompatibilitet med äldre protokollklienter
Håll protokollgenerationen konsekvent i klienter som fortfarande använder initieringshandskakningen.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Skicka initialize och läs protokollversionen och de capabilities som servern har förhandlat fram.
- Skicka den notifiering om slutförd initiering som klientens protokoll kräver; en notifiering ger inget vanligt verktygsresultat.
- Använd tools/list för att läsa de verktyg som den aktuella auktoriseringen omfattar och skicka sedan tools/call.
- Håll huvuden och meddelanden konsekventa med den aktuella förfrågans protokollgeneration; använd inte det gamla initialize- eller ping-flödet för meddelanden enligt 2026-07-28.
Det äldre protokollet använder fortfarande samma Bearer/OAuth, behörigheter och verktygskontrakt. Det innebär inte att servern nödvändigtvis erbjuder äldre långlivade SSE-anslutningar eller Mcp-Session-Id; de offentliga tjänsterna i r56 är tillståndslösa.
Protokollfel
| Situation | Typiskt resultat | Åtgärd |
|---|---|---|
| Moderna huvuden och meddelanden stämmer inte överens | HTTP 400 JSON-RPC -32020 | Rätta huvuden, metadata och verktygsnamn |
| Version som inte stöds | -32022 tillsammans med en lista över versioner som stöds | Välj ett protokoll som faktiskt stöds |
| Okänd metod | JSON-RPC -32601, moderna förfrågningar kan ge HTTP 404 | Kontrollera protokollgeneration och metod |
| Saknade eller ogiltiga parametrar | JSON-RPC parameterfel eller verktygets isError | Rätta enligt det faktiska inputSchema |
Välj rätt verktyg och beviskanal
Välj väg utifrån den affärsfråga som ännu är obesvarad och upprepa inte bevisinhämtningen genom en fast anropskedja.
| Uppgift | Förstahandsverktyg | Bevis som krävs för slutförande |
|---|---|---|
| Identifiera auktoriserade ämnen och resurser | dfc_ontologies dfc_ontology_resources | Faktiska typer av resurs-ID och det omfång som är synligt just nu |
| Tabellstatistik och TopN | dfc_table query | Kvitto på lyckad körning samt fullständiga evidenceRows |
| Slå upp regelverk, kontrakt eller rapporter | dfc_ontology_query eller knowledge search/detail | Fullständig, auktoriserad originaltext som kan användas som fakta |
| Lokalisera grafobjekt | dfc_ontology_graph search/neighbors | Lokalisera den faktiska källan och hämta därefter motsvarande fakta |
| Nyckelordsinteraktion i den inbyggda Search | dfc_manual därefter dfc_search | Faktiska resultat i den ursprungliga modellen och affärsramen |
| Kombinerad analys och rapportering | dfc_analysis_* eller dfc_report_* | Verkligt tillstånd för varje strukturerad gren och dokumentbevis |
| Ändra presentation eller ontologimodell | dfc_authoring_* och artifact-verktyg | Kontrollera kandidat, plan, godkännande och faktisk tillämpning var för sig |
| Kör affärskommandon | dfb_* i /mcp/business | Publicerat kontrakt och kvitto från den ursprungliga ActionPlan |
Undvik onödiga anrop
När en aktuell, fullständig och auktoriserad tabellstruktur redan finns ska inte varje fråga kräva en ny detail; när tillförlitlig lokalisering och bevis redan finns ska inte samma sökning upprepas. Om en dimension saknas gör du en avgränsad kompletterande fråga. När ett fel uttryckligen inte kan försökas igen ska luckan åtgärdas först; ”försök igen” ersätter inte en bedömning.
Det som inte ingår i Flash
dfc_etl capabilities kan returnera available=false samt ETL_NOT_INCLUDED_IN_OT_FLASH. Den statiska beskrivningen av inbyggda ETL-funktioner är avsedd som referens mellan produkter. Den bevisar inte att ETL är installerat i Flash och tillåter inte att agenten automatiskt växlar till Heavy eller en annan tenant för att köra.
Ontologiresurser och ID-typer
Hämta först faktiska resurskoordinater för att undvika att förväxla lagringsnamn, dokument-ID och kunskapsbas-ID.
- Anropa dfc_ontologies och bläddra med page och pageSize bland de ontologier som omfattas av den här auktoriseringen och fortfarande kan läsas.
- Anropa dfc_ontology_resources med ett verkligt ontologyId; välj vid behov tables, answers, pinboards, documents och knowledgeBindings.
- Hantera sidnumrering för varje resurstyp var för sig. pageSize är högst 100; dra inte slutsatser om hela resursomfånget utifrån den första sidan.
- Spara den typ som resursen deklarerar och det ursprungliga ID:t och använd dem oförändrade i senare anrop.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Koordinat | Källa | Kan inte ersätta |
|---|---|---|
| ontologyId | Auktoriserad ontologilista eller aktuell giltig kontext | ID för en annan ontologi |
| Tabellresursens id | tables-listan eller tillförlitlig kontext | physicalName eller tabellens visningsnamn |
| tblDisplayName colDisplayName | Aktuell tabell- och kolumnmetadata | Gissade fysiska SQL-identifierare |
| knowledgeId | knowledgeBindings eller kvitto från en faktisk kunskapssökning | Dokumentresursens id |
| assetId documentId chunkId evidenceId | Samma faktiska lokaliseringskvitto | Fält som sammanfogats från olika lokaliseringsresultat |
| rid revisionId releaseId | Publicerad modell eller kandidatkontext på servern | Självskapade ID:n eller latest |
Konventioner för precision
Alla 64-bitars resursidentifierare skickas i första hand som decimalsträngar och konverteras inte via Number i JavaScript. Vissa affärsscheman godtar string eller integer, vilket inte innebär att heltalsprecision får kasseras. Opaka locators, UUID, hashvärden och engångstokens sparas också oförändrade.
Doris-tabellfrågor och strukturkontrakt
Kör skrivskyddad SQL mot auktoriserade tabeller och bevara utdatasemantik, exakta värden och fullständighet.
Läs strukturen
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}detail använder det verkliga tabellresurs-ID:t. Kontrollera schemaComplete, tblDisplayName, colDisplayName i columns och den auktoritativa sqlDataType samt den returnerade queryContract. dataType är endast en kompatibilitetsmappning; det fysiska lagringsnamnet är inte det tabellnamn som ska användas i SQL.
Kör frågor
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}SQL-begränsningar
- Använd tabellernas och kolumnernas visningsnamn och omge identifierare med dubbla citattecken. Förfrågan ska vara en skrivskyddad Doris-fråga inom ontologins omfång.
- Ange utdatakolumnerna explicit; SELECT * och table.* är förbjudna; de kan inte användas för att kringgå behörigheterna för registrerade kolumner via fysiska kolumner.
- Kopplingar görs med explicit JOIN ... ON; NATURAL JOIN och JOIN USING avvisas.
- Giltiga flerdimensionella aggregeringar, CTE:er, fönsterfunktioner, CASE, COUNT(DISTINCT ...) och andra skrivskyddade uttryck kan användas; att den semantiska valideringen inte täcker ett visst uttryck innebär inte att det generellt är förbjudet att köra det.
- Utför aggregering, sortering och rankning först i SQL och tillämpa därefter resultatgränsen. maxRows är som standard 100 och högst 200.
Datum och tidszon
| Typ eller mål | Skrivsätt | Observera |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) och CURRENT_DATE | Anta inte att en textliteral automatiskt har datumtyp |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) och CURRENT_TIMESTAMP | Kontrollera källans tidszon och sessionens tidszon |
| Relativ tid | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Använd motsvarande funktion för aktuellt datum respektive aktuell tidsstämpel |
| Tidsgruppering | YEAR(column) eller DATE_TRUNC(column, 'month') | Använd ett unikt alias för varje utdata; queryContract är avgörande |
SQLite:s DATE('now', ...) ingår inte i Doris datumkontrakt för den här ingången. För inte över dokumentationsexemplens offlinekontroll med SQLite till SQL som körs i drift.
Läs v8-frågekvittot
evidenceRows är agentens enda kanal för raddata; rådata (raw data) exponeras inte för agenten. SQL-tal kodas som exakta decimalsträngar i JSON; använd resultColumnContracts för att avgöra deras numeriska och affärsmässiga typ, och tolka dem inte som VARCHAR enbart för att JSON är en sträng. Läs executionReceipt samt fullständighets- och trunkeringsinformation och behåll källinformation som evidenceRowsSha256.
Frågeutdata med ett citerbart exekveringskvitto kan citeras som de är; endast semantik som servern har verifierat kan ligga till grund för efterföljande deterministiska sekundärberäkningar. Gissa inte ”ackumulerat saldo”, ”värde vid periodens slut” eller ”币种” utifrån fältnamn och lägg inte till enheter på egen hand. Nollradsresultat, fel eller trunkering får inte beskrivas som fullständig statistik.
Flerdimensionell Top3 och trunkeringshantering
Besvara rankningsfrågor med aggregering och fönsterfunktioner på servern; gör inga sekundärberäkningar på ofullständiga resultat.
Det medföljande examples/top3.sql använder exempeltabellen: det aggregerar först per 区域, 类别 och 产品, kör sedan ROW_NUMBER inom varje kombination av 区域 och 类别 och använder 产品-namnet som stabil ordning vid lika belopp. Att begära maxRows=100 räcker för exemplets 36 rader; för andra affärsdata måste du utgå från det verkliga antalet grupper.
- Hämta den verkliga strukturen och aktuella affärsdefinitionen; klargör 币种, period, 订单状态 och regler vid lika värden.
- Skicka SQL som gör aggregeringen och rankningen på servern. Fråga inte först bara efter totalen per 区域 för att sedan använda den som rankning av 类别 och 产品.
- Kontrollera utdatakolumnernas kontrakt mot de faktiska evidenceRows och bekräfta att svaret täcker alla nödvändiga grupper.
- Om trunkering upptäcks: gör avgränsade, partitionerade frågor inom de gränser som servern stöder, t.ex. en fullständig Top3 per 区域; behåll samma affärsdefinition i varje fråga.
- Om källperioden ändras: fråga igen och klargör den nya versionen; blanda inte olika dataversioner och använd inte ogiltiga markörer.
Felåterställning
TABLE_SCHEMA_INCOMPLETE innebär att du ska rätta strukturen eller hämta den fullständiga strukturen; fel som ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID hanteras enligt den returnerade errorCode, retryable och remediation. Påstå inte att ”alla flerdimensionella GROUP BY eller fönsterfunktioner är förbjudna”, och hitta inte på rankningar när det saknas frågeresultat.
Kunskapssökning, fullständig originaltext och bevisgiltighet
Håll isär lokalisering, läsning och citering av fakta, och bevara källhänvisning och fullständighet.
Två vanliga vägar
| Väg | Syfte | Viktigt |
|---|---|---|
| dfc_ontology_query | Söker i kunskap som är bunden till ontologin, eventuellt i kombination med grafroutning | Kontrollera fullständiga canonical answerContextItems och bevisgiltighet |
| dfc_knowledge_search → dfc_knowledge_detail-chunk | Lokalisera med en explicit sökning och läs sedan valda fragment | Förhandsvisningar i sökresultat räknas inte som fakta; läs den fullständiga originaltexten för samma 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>"
}}Villkor för att kunna användas som fakta
- Kontrollera aktuell ACL, innehållets fullständighet samt serversidans canonicalFactEligible, citationEligible eller motsvarande exekveringskontrakt.
- Fullständigt innehåll är bundet till contentSha256. Trunkering, utelämnanden på grund av budget och innehåll av låg kvalitet ska hanteras enligt de faktiska fälten.
- Dokumentmetadata, page_context, graflokalisering, sökningssammanfattningar och förhandsvisningar kan inte ersätta den canonical originaltexten.
- Kopiera i första hand evidenceId; om du behöver chunkId och documentId måste de komma från samma lokaliseringsresultat; sätt inte ihop eller gissa fram dem.
Grafroutning
Resultaten från search/neighbors är lokaliseringsinformation. Skicka till ontologins query endast det routeLocator-objekt som servern har returnerat i sin helhet, inklusive bindnings-, versions- och bevisfält. Paketera inte på egen hand ett assetId eller knowledgeId som en locator utfärdad av servern, och skicka inte tillbaka källbevis som modellen bara har påstått.
Strukturerad dokumentrekonstruktion
dfc_ontology_query:s structuredPlan är en begränsad rekonstruktion med deterministisk validering, särskilt avsedd för tabeller i oregelbundna dokument. Använd den plan som servern deklarerar endast när den har returnerat aktuell executionContractSha256, tableIndex, kolumnerna och den fullständiga tabellen. Vanliga importerade affärstabeller ska frågas via dfc_table SQL; använd inte rekonstruktion av Markdown-tabeller som en väg förbi auktoriseringen av tabellfrågor.
Sökstrategi
knowledgeIds utelämnas normalt så att alla bindningar som är aktiva just nu omfattas; om det anges får endast verkliga kunskapsbas-ID:n från knowledgeBindings användas. Behandla inte ett dokumentresurs-ID som ett kunskapsbas-ID. Gör nya avgränsade sökningar utifrån frågor som ännu är obesvarade och undvik exakt upprepade sökningar som inte ger nya bevis.
Inbyggd Search-modell och session
Använd nyckelordsprotokollet i Rust Search via dfc_search och vänta tills den ursprungliga affärsramen når sitt sluttillstånd.
Läs beskrivningen först och identifiera sedan funktionerna
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search kräver ett uttryckligt search:operate. Verktyget omsluter den ursprungliga WebSocket-anslutningen för nyckelord och skriver inte om nyckelord till SQL- eller LLM-förfrågningar. Sessionen är bunden till den aktuella tenanten, användaren, Grant, klienten och modellen; vid varje åtgärd kontrolleras de ursprungliga tabell- och kolumnbehörigheterna på nytt.
Minimalt sessionsflöde
{"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":[]}}}
}}- Använd model_create med 1 till 100 verkliga tabell-ID:n som du har behörighet till, eller model_read för att läsa en befintlig sourceToken som du själv äger.
- open returnerar endast initializationSent; anropa först poll, läs det ursprungliga affärssvaret på init och bekräfta att det lyckades.
- Läs assist och förslagen och skicka sedan ett ursprungligt message som stöds. I datas för query sätter omslaget alltid isNl till false.
- Läs frames kontinuerligt och skilj mellan förslag, tolkning, mottagning och slutligt affärsresultat.
- Avsluta med close. Använd cancel när något ska avbrytas och kontrollera mot den verkliga uppgiftsstatusen att det faktiskt har avslutats.
| action | data | Betydelse |
|---|---|---|
| capabilities | Utelämnas eller tomt objekt | Läser åtgärder, kommandon, TTL och transportinformation |
| model_create | tableIds-array | Skapar en auktoriserad modell för den aktuella användaren |
| model_read | sourceToken | Läser modellen och filtrerar bort kolumner utan behörighet och känsliga källkonfigurationer |
| open | sourceToken samt valfri language | Upprättar en inbyggd session och skickar init |
| request | sessionId och message | Skickar ett meddelande i det ursprungliga type/datas-protokollet |
| poll | sessionId och waitMillis 0 till 30000 | Hämtar de ramar som finns i bufferten och kan vänta en begränsad tid |
| cancel close | sessionId | Stänger den här inbyggda sessionen; kan inte fastställa BI-sluttillståndet |
Ursprungliga kommandon som stöds
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteKommandonas versaler/gemener och datas-strukturen följer aktuella capabilities och det ursprungliga sessionsprotokollet. Lägg inte till åtgärder som inte finns i request; stavningen disambiguite måste till exempel behållas enligt det faktiska protokollet. Ett meddelande får vara högst 256 Ki tecken.
Session och fullständighet
Sessionens TTL är 10 minuter, och sessionen finns bara kvar så länge den aktuella processen lever; den är ingen beständig uppgift som kan återupptas. Bufferten rymmer högst 256 ramar och begränsas av minnesgränsen; när bufferOverflow=true får hämtade ramar inte betraktas som ett fullständigt resultat. Efter ett transportfel anropar du först poll för den ursprungliga sessionen och skickar inte blint om en fråga som kanske redan har körts.
Det aktuella omslaget kan inte spara svar eller pinboards, läsa eller skriva historik eller återställa godtycklig kontext. Att exportContext finns innebär inte att du själv kan återställa godtycklig kontext. Om resultat behöver sparas använder du de ursprungliga resursfunktioner som instansen faktiskt erbjuder; hitta inte på någon action.
Språk och regionala konventioner
Håll isär UI-locale, frågeordlistor, svarsspråk och ursprungliga fältnamn.
Prioritetsordningen är: uttryckligen begärt språk, applikationssystemets språk och därefter locale på den nod som faktiskt kör anropet. Ett utelämnat värde, null, en tom sträng eller enbart blanksteg ger inte automatiskt kinesiska som reservspråk. De regionala värdena i languageRegistry ska behållas exakt; en-GB, fr-CA, pt-BR, es-US och ar-AE får inte godtyckligt slås ihop med en annan region.
| Språk eller region | Frågelocale | Beskrivning |
|---|---|---|
| Förenklad kinesiska, traditionell kinesiska | zh-CN zh-Hant | De ursprungliga kinesiska reglerna skiljer sig från katalogen för traditionell kinesiska |
| Amerikansk, brittisk, australisk och kanadensisk engelska | en-US en-GB en-AU en-CA | UI- och nyckelordspaket kan delas; regionsmetadata behålls |
| Tyska, italienska, ryska | de-DE it-IT ru-RU | Använd enligt förslagen i den aktuella sessionen |
| Spanska (Spanien) och latinamerikansk spanska | es-ES es-US | Produktens region-ID är es-US |
| Franska (Frankrike) och kanadensisk franska | fr-FR fr-CA | Region-ID:n slås inte samman |
| Portugisiska (Portugal) och brasiliansk portugisiska | pt-PT pt-BR | Katalog- och regionkonventioner behålls separat |
| Nederländska, danska, norska, finska, svenska | nl-NL da-DK nb-NO fi-FI sv-SE | Norska avser bokmål |
| Japanska, koreanska | ja-JP ko-KR | Ord delas inte upp enligt engelska mellanslagsregler |
| Saudiarabisk och emiratisk arabiska | ar-SA ar-AE | Gränssnittstexter stöder RTL; protokollidentifierare vänds inte |
Använd nyckelordskatalogen
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}dfc_manual:s statiska nyckelordskatalog omfattar endast uttryckligen listade locales; om locale utelämnas används den engelska referensen. Detta är ett standardvärde för referensen, inte en regel för hur frågespråket tolkas. Om det saknas en statisk katalog för en regional variant hämtar du faktiska förslag via assist i den aktuella sessionen; hitta inte på alias eller reservresultat. names får innehålla högst 32 poster per anrop.
Innehåll som inte översätts
- Tabeller, kolumner, enumvärden, kundnamn, formelnamn och andra verkliga modellsträngar.
- Verktygsnamn, action, scope, schema-fält, felkoder och statusvärden.
- Resurs-ID:n, hashvärden, opaka locators och referenser utfärdade av servern.
En fråga på tyska kan till exempel ställas mot den kinesiska visningskolumnen ”销售金额”. Om den byts ut mot ett tyskt kolumnnamn blir det en annan identifierare, inte en översättning av gränssnittet. Efter ett språkbyte initierar du om sessionen eller uppdaterar den enligt det ursprungliga protokollet och hämtar förslag och tvetydighetskandidater på nytt.
Kombinerad analys och interaktiva resultat
Bevara auktorisering, version, gren och bevisstatus i de villkorligt tillgängliga analysverktygen.
dfc_analysis_* styrs av datafocus.mcp.analysis.tools.enabled. Den strukturerade delen går fortfarande via auktoritativa frågor i Search och den aktuella radpolicyn; dokumentdelen hämtar på nytt den fullständiga originaltexten under aktuell ACL. De är ingen ingång för öppen SQL, godtyckliga instruktioner eller injektion av godtyckliga filter.
| Verktyg | Syfte | Nödvändiga koordinater |
|---|---|---|
| dfc_analysis_ask | Ställer en analysfråga på naturligt språk | ontologyId question, valfritt language sessionId |
| dfc_analysis_result_get | Läser ett tidigare returnerat resultat | ontologyId sessionId resultId |
| dfc_analysis_refine | Ställer uppföljningsfrågor eller gör ändringar utifrån det senaste fullständiga resultatet | Ursprungligt resultat, expectedRevision och stabil idempotensnyckel |
| dfc_analysis_page | Hämtar en sida från en gren på servern | Ursprunglig gren och resultatversion pageNo pageSize |
| dfc_analysis_cancel | Avbryter ett resultat som fortfarande bearbetas | Ursprunglig session och resultat |
| dfc_analysis_close | Frigör en session som inte längre arbetar | Ursprunglig session |
Starta en analys
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Läs returnerade sessionId, resultId, status och revision; fortsätt vid behov att läsa det ursprungliga resultatet.
- Kontrollera varje strukturerad grens status, fullständighet, radpolicy och källor; att en gren är klar innebär inte att hela analysen är fullständig.
- Granska dokumentbevis, faktaregistret, citerbarhet och begränsningar. Text som modellen genererar kan inte på egen hand höja bevisens giltighet.
- Vid uppföljningsfrågor utgår du från det senaste fullständiga resultatet och skickar med expectedRevision; återförsök av samma ändring ska återanvända samma idempotensnyckel.
- Kontrollera innan du stänger att sessionen inte längre arbetar; att avbryta och att stänga är olika åtgärder.
Kontrollerad filtrering och sidnumrering
filter_patch använder branchId, fieldRef, valueRef och tillåtna operatorer från servern; de typade filtren deklarerar för närvarande endast EQ. Använd aldrig rå SQL, tableId eller columnId eller klientgenererade filterträd i stället för opaka referenser. Vid sidnumrering börjar pageNo på 1 och är högst 10000; pageSize är högst 100.
Funktionstips och beteende
Verktygens annotations är tips till klienten, inte säkerhetsauktorisering. Vissa generella mallar använder readOnlyHint, men det ersätter inte en bedömning av den faktiska åtgärden; att avbryta, stänga och skapa rapporter ändrar motsvarande arbetstillstånd. Följ alltid verktygets semantik, användarens mål och serverns behörigheter.
Beständiga visualiseringsrapporter och MCP Apps
Skapa rapporter som kan återupptas och läs deras resultat och interaktiva gränssnitt enligt aktuella behörigheter.
dfc_report_* styrs av datafocus.mcp.analysis.report-tools.enabled och kräver metadata- och table query-scope. Till skillnad från Search-sessioner, som bara finns inom processen, använder rapporter ett beständigt reportId; beständigheten innebär inte att behörigheterna slutar kontrolleras.
{"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>"
}}Arbetsflöde
- Använd en stabil idempotencyKey när rapporten skapas, med 8 till 128 tecken av de typer som stöds.
- Spara reportId, polla status och kontrollera det faktiska tillståndet, till exempel slutförd, misslyckad, delvis slutförd eller avbruten.
- När du läser resultatet kontrollerar du strukturerade grenar, visualiseringar, faktakällor, dokumentreferenser och fullständighet.
- Använd det ursprungliga reportId för att avbryta en ofärdig rapport; skapa inte en ny rapport i stället för att avbryta.
- Efter en nätverkstimeout läser du först den ursprungliga rapportens status; en upprepning med samma idempotensnyckel ska avse samma affärsavsikt.
MCP Apps
Klienter med stöd för UI-tillägg läser rapportsidor via verktygets _meta och discovery av faktiska resurser. Den beständiga rapportsidan för r56 är ui://datafocus/analysis-report/v16/index.html; interaktiv analys använder motsvarande resursreferenser från servern. Klienten ska inte hårdkoda värden som ersätter verktygets returvärden. Även utan UI-tillägg kan strukturerade resultat läsas.
Origin-bindning
När en rapport läses kontrolleras Grant, ontologi, bindningen till förfrågans Origin och aktuella tabellbehörigheter på nytt. Integration i webbläsaren mellan olika ursprung (cross-origin) kräver ett godkänt, faktiskt ursprung; klienten får inte kringgå bindningen med en förfalskad Origin. Ett gammalt reportId är varken en långlivad offentlig länk eller en åtkomstbehörighet mellan användare.
Artefaktutkast, förhandsvisning, plan och tillämpning
Låt den ursprungliga servern normalisera, validera och godkänna genererat innehåll; låt inte modellen ändra produktionsresurser direkt.
Artefaktverktygen kräver att authoring-funktionen är aktiverad, en faktisk artifact type, berörda scope och den ursprungliga skrivbehörigheten som administratör. Som standard är typerna CONTROL_PANEL_SPEC och VIEW_SPEC konfigurerade; andra typer som formulär, HTTP-källor eller skript styrs dessutom av separata konfigurationer. Flash har ingen AutoML, och därför listas de typerna inte som tillgängliga artefakter i den här versionen.
- dfc_authoring_capabilities läser de kontrakt och åtgärder som är tillgängliga för det aktuella Grant.
- dfc_artifact_context hämtar avgränsad kontext, contractVersion, contextHash, baseArtifactHash och baseArtifactVersion.
- Generera kandidaten i klienten utifrån det verkliga kontraktet, utan att köra någon kod i den.
- dfc_artifact_submit skickar in den ursprungliga kontexten och kandidaten med oförändrad instruction och använder ett stabilt clientRequestId.
- Läs proposalId, candidateHash, valideringsresultat och förhandsvisning; vid faktiska fel reviderar du kandidaten och hittar aldrig på att servern har godkänt den.
- Om en ny förhandsvisning behövs använder du dfc_artifact_preview och samma kandidathash.
- dfc_artifact_plan skapar en oföränderlig plan med den verkliga kandidaten, målversionen och en idempotensnyckel.
- Hantera godkännandet via det ursprungliga interaktiva godkännandeflödet eller en redan auktoriserad policy och anropa därefter dfc_artifact_apply; endast ett APPLIED-kvitto innebär att ändringen faktiskt har tillämpats.
Minimal kontextförfrågan
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC använder det auktoriserade projectId; vid redigering av en befintlig artefakt används det faktiska artifactId. Fält som variables, previewInput och viewport anges enligt det returnerade kontraktet; gissa inte kandidatens interna struktur.
Samtidighet och återförsök
Planen är bunden till målversion, kandidathash och idempotensnyckel. När målet har ändrats kan den gamla planen inte längre tillämpas; läs kontexten på nytt och hantera de faktiska konflikterna. En transporttimeout bevisar inte att anropet misslyckades; fråga först med dfc_artifact_status efter det ursprungliga proposalId eller planId. READY är inte APPLIED.
Godkännande och automatisk policy
Generella artefaktplaner kräver det ursprungliga manuella godkännandet. Planer som omfattas av ontologins policy för automatisk publicering hanteras enligt approvalMode och kräver inte att användaren dessutom undertecknar ett godkännande som agenten har hittat på. approvalToken är material som utfärdas av servern och kan inte ersättas av en sträng som agenten skriver; det faktiska inputSchema och plankvittot avgör vilka fält som är obligatoriska.
Skapande av ontologikandidater och publiceringskontrakt
Använd ontologideklarationer och publiceringskonfigurationer med egen versionering; tillämpa inte kontraktet för vanliga presentationsartefakter på modellpublicering.
Skapa kandidat
Ontologicontainern måste redan finnas och ingå i Grant. Använd dfc_ontology_table_schema för att kontrollera aktuella strukturerade källfält och v4 Binding-fingeravtryck; för ett fält räcker det att ange sourceField för att typen ska identifieras automatiskt. Explicita DECIMAL-deklarationer kräver aktuell precision och antal decimaler; andra typer har inte dessa två fält.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Kandidater och publiceringskonfiguration
| Kontrakt | Syfte | Viktiga gränser |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Skapar en kandidat från lokala deklarationer | Verkliga auktoriserade källor och kompilering på servern; bevis på slutförande accepteras inte |
| ontology-workspace-create-mcp-submit-v2 | Blandar lokala deklarationer och exakta publicerade referenser | Ange exakta releaseSelections och beroendehöljet |
| ontology-publication-mcp-submit-v1 till v3 | Binder en befintlig kandidat till en förfrågan om publiceringsplan | Explicita koordinater; mål, källa, godkännande och validering återställs av servern |
| ontology-publication-mcp-submit-v4 till v6 | Separat aktiverad konfiguration för automatisk publicering | Används endast när capabilities och det faktiska schemat deklarerar den |
| ontology-initial-activation-retirement-submit-v1 | Kontrollerad initial aktivering och avveckling | Separat plan, nytt manuellt godkännande och exakt omfång |
Steg för publicering
- Hämta den aktuella kandidatens workspaceId, workspaceRevision, candidateHash och den faktiska källan.
- Välj kontraktsversion enligt serverns funktioner; skicka in koordinater som releases och selection, utan fält som påstår att något är ”godkänt” eller ”har passerat”.
- Spara proposalId och den ursprungliga idempotencyKey från submit. Submit och MODEL_PLAN är olika faser av samma förfrågan.
- Anropa dfc_artifact_plan med den ursprungliga kandidaten, målversionen och samma idempotensnyckel.
- PLANNING_INCOMPLETE betyder endast att ingen giltig plan har skapats ännu; VALIDATION_UNSATISFIED betyder att den aktuella valideringen fortfarande har luckor; hantera dem enligt nextAction.
- När planen har lyckats fortsätter du enligt HUMAN_REQUIRED eller POLICY_AUTO och använder det ursprungliga godkännande- och publiceringsflödet.
- Bekräfta resultatet med ett APPLIED-kvitto och därefter med en verklig läsning av den publicerade modellen och en auktoriserad fråga.
Timeout och återställning
Efter en PLAN-timeout läser du det ursprungliga proposalId. MODEL_PLAN_SUBMITTED är en ofullbordad förfrågan; MODEL_PLAN_COMPLETED betyder att det ursprungliga kvittot ska återställas med de ursprungliga koordinaterna och nyckeln, inte att klienten ska skapa en ny förfrågan. Valideringsluckor i sluttillståndet kan inte omvandlas till en godkänd publicering genom att byta nyckel eller skicka in på nytt.
Mänskliga affärsbehörigheter
Agentens instruction och deklarationer är indata från agenten, inte en policy som en människa har undertecknat. MODEL_AUTHOR, MODEL_PUBLISH, delegering av automatisk publicering, affärsbekräftelse, förtroende för offentliga nycklar, budget och källans ACL avgörs fortsatt av de ursprungliga mekanismerna. Klientfält får inte ersätta dessa fakta.
Publicerad modell, kandidatfrågor och referenshölje
Använd publicerad affärskunskap med exakt version och behåll den tillfälliga karaktären hos opublicerade kandidater.
dfc_ontology_graph:s published_model, published_query och candidate_query är villkorligt tillgängliga strukturerade konfigurationer, inte synonymer till vanliga search/neighbors. De auktoriseras via table query och nödvändiga läsbehörigheter för modellering; att något syns i grafen ersätter inte tabellbehörigheter.
Läs en publicerad modell
- När verktygets action-enum faktiskt innehåller published_model skickar du in ett verkligt committed releaseId.
- v1 returnerar auktoriserade frågemallar; v2 lägger till exakta PERSISTED-referenser och releaseSelections; v3 lägger till beroendereferenser, exakt domainRef och kompakta bindningsmallar.
- Välj objekt, attribut, Binding, scope och version från faktiska returvärden; generera inte RIDs och använd inte latest.
- Skicka in den fasta typade frågan för published_query; resultatet måste fortfarande klara den aktuella auktoriseringen av källor och fält.
Kandidatfrågor
candidate_query använder det faktiska workspaceId, revision, candidateHash och kandidatdeklaration. Vid blandning med publicerade referenser används motsvarande v2-typade LOCAL/PERSISTED-koordinater och exakta urval. Kandidatresultat är alltid opublicerade och tillfälliga och får inte behandlas som kunskap som företaget har bekräftat.
Lokalt underhåll och hölje
Välj endast de transitiva beroenden som kandidatroten kräver och se till att varje publicerad referens har en exakt releaseSelections. Att kopiera publiceringens innehåll, bara skicka in en uppsättning ID:n eller utvidga till alla historiska resurser ersätter inte kontrollen av aktuella beroenden och källor.
För dessa actions är query ett versionerat, typat objekt; SQL, fysiska tabell-ID:n eller källtabellnamn accepteras inte i stället för dess affärsreferenser. Metadatamallar och grafresultat är i sig inte giltiga som faktareferenser.
Delegerade uppgifter för ontologiagenten
Återuppta arbetet med beständiga uppgifter och det ursprungliga Grant; behandla inte agentens instruktioner som ett mänskligt godkännande.
dfc_ontology_agent visas endast när en faktisk Pi Runtime och berörda behörigheter finns tillgängliga. QUERY använder läsfunktionerna; AUTHORING kräver dessutom en modelleringsroll och motsvarande authoring-scope. Verktyget öppnar ingen separat exekveringsmotor utan begränsningar.
{"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>"
}}Strikt parameteruppsättning
start använder contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel använder contractVersion, action, ontologyId, runId. Servern kontrollerar den exakta fältuppsättningen per action. instruction får vara högst 16000 tecken; nycklar består av 1 till 128 tecken av de typer som stöds och börjar med en bokstav eller siffra.
Återupptagande och avbrytande
- Spara det ursprungliga runId, Grant, mode och idempotensnyckeln.
- Samma nyckel med samma instruction återupptar samma run och skickar inte in någon ny uppgift; samma nyckel med en annan instruction avvisas.
- status hämtar den ursprungliga uppgiftens status. Även när uppgiften är slutförd måste dess tabellfrågor, bevis eller publiceringskvitton kontrolleras.
- Avbryt med det ursprungliga runId; bekräfta resultatet med uppgiftens faktiska status.
En avslutad run är inte ett kvitto på modellpublicering. Publiceringsuppgifter bekräftas fortfarande via den ursprungliga artefaktens status och källkontroller; QUERY medför ingen underförstådd skriv- eller publiceringsrätt.
MCP för affärsarbetsytan
Fråga efter poster utifrån publicerade affärskontrakt och kör kommandon via den ursprungliga ActionPlan.
/mcp/business använder en separat protected resource och val av affärssystem; ett Grant för ontologin kan inte återanvändas i stället för affärsauktorisering. Affärssystemet måste vara publicerat, tillgängligt för anrop från agenter och uppfylla den ursprungliga säkerhetspolicyn, och den aktuella användaren måste ha faktiska runtime-roller och funktioner.
| Scope | Verktyg | Avgränsning |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Identifierar endast system som omfattas av den här auktoriseringen och som går att anropa just nu |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Poster som den aktuella användaren kan läsa samt användarens egna planer |
| business-system:plan | dfb_action_plan | Skapar endast oföränderliga planer, exekverar inte |
| business-system:execute | dfb_action_execute | Separat, uttrycklig auktorisering; körs enligt risk och godkännande |
- dfb_systems identifierar auktoriserade system.
- dfb_system_describe läser det aktuella publicerade kontraktet, releaseId samt alla hashvärden, frågor och kommandon.
- dfb_query använder publicerad queryKey och anger vid behov objectKey, state, page och pageSize. Det är inte godtycklig SQL.
- dfb_record och dfb_work_items läser de poster och väntande uppgifter som för närvarande är tillåtna.
- Före exekvering anger du med dfb_action_plan det faktiska releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey och kontraktets payload.
- Kontrollera riskClass, requiresApproval och status; när en målpost berörs ska du behålla expectedRecordVersion.
- dfb_action_execute exekverar endast planer som den aktuella anslutningen äger och som är redo; de godkännandetokens som krävs för manuellt godkännande utfärdas av DataFocus.
- Efter fel eller timeout använder du dfb_action_status för att återuppta den ursprungliga planen; återförsök behåller den ursprungliga idempotenssemantiken.
Anslutning och versionsbindning
Planen är bunden till det aktuella Grant via dess stabila isolerings-ID. När access token har förnyats kan samma anslutnings planer fortfarande hanteras, men en annan OAuth-anslutning kan inte ta över dem. Vid körning kontrolleras publicerad version, IR/manifest-hash, målpostversion, planens utgång, idempotens och godkännande på nytt. OAuth-allowlistan kan inte kringgå affärsstyrningen.
Inmatning av affärskunskap och frågor som väntar på bekräftelse
Registrera affärsinmatning när motsvarande produktionsprocessor är aktiverad och behåll gränsen för mänsklig bekräftelse.
Följande fyra verktyg läggs till villkorligt av den offentliga MCP-kontrollern beroende på installerade processorer och aktuellt scope. De visas inte alltid i baskatalogen. Att ett schema deklareras innebär inte att instansen har alla processorer, budget och behörigheter på plats; kontrollera alltid tools/list först.
| Verktyg | Syfte | Auktoriseringar och effekter som inte uppstår |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registrerar den ursprungliga affärsinmatningen för en befintlig arbetsyta | Genererar inga bekräftelsefrågor, godkänner inte, publicerar inte |
| dfc_ontology_knowledge_input_preview | Förhandsvisar tillfälligt frågeutkast utifrån den ursprungliga inmatningen | Sparas inte beständigt, bekräftar inte, ger inget produktionskvitto |
| dfc_ontology_knowledge_question_submit | Sparar frågor som är authored och ännu inte bekräftade | Slår inte automatiskt ihop svar; ger ingen ansvarsbehörighet eller publiceringsrätt |
| dfc_ontology_business_scope_initialize | Initierar uttryckligen ett konsumentscope för ett affärssystem | Publicerar inte, aktiverar inte, beviljar inte källåtkomst |
Inmatning och förhandsvisning
- Hämta workspaceId, workspaceRevision, localRef och preparationDigest från det faktiska förberedelsearbetet.
- propose registrerar affärsinmatning med det ursprungliga input-kontraktet och ett stabilt idempotencyKey; samma nyckel får bara motsvara samma inmatning.
- preview använder den ursprungliga inmatningens idempotensnyckel och ontologyId; den returnerar varje gång serverns revision och ett 60-sekundersfönster och är inte ett idempotent kvitto på slutförd produktion.
- När frågor behöver lagras använder question_submit en ny kommandonyckel, den ursprungliga originalInputKey, en uttrycklig questionRevision, validFrom, validUntil och expectedRevision; vid skapande är expectedRevision null.
Ingång för mänsklig bekräftelse
knowledgeConfirmationPage som returneras av question_submit är endast en relativ adress till den ursprungliga inloggningssidan, där en viss fråga är förifylld. Den innehåller ingen Bearer, öppnar inte sidan automatiskt och bekräftar inte kunskap. QUESTION_STORED_UNCONFIRMED anger uttryckligen att frågan ännu inte är bekräftad, och det får inte beskrivas som att ”kunskapen har publicerats” i svaret.
Initiering av konsumentscope
business scope initialize kräver både publiceringsrätt för ontologin och att användaren är skapare av eller har SourceManager-administratörsrätt för det exakta affärssystemet. Den använder verkliga koordinater för domainRid, domainRevisionId och businessSystemId; klienten kan inte fylla i godtycklig consumerScope eller bevis på slutförande. Även när INITIALIZED och COMPLETED returneras anges fortfarande uttryckligen published=false och activationAuthorized=false.
Dessa förfrågningar genomgår dessutom strikt JSON-validering samt kontroll av fältuppsättning, storlek i byte och djup. Gränsen för indataförfrågningar är 1 MiB; vissa specifika operationer har lägre gränser. Fullständiga in- och utdatascheman levereras med verktygsreferensen; den toleranta parameterlogiken i det allmänna MCP-omslaget får inte tillämpas på dessa strikta kontrakt.
Svar, fel och säkra återförsök
Tolka fel lager för lager och bevara uppgiftskoordinater och idempotenssemantik.
| Lager | Vad som kontrolleras | Hanteringsprincip |
|---|---|---|
| Nätverk och HTTP | Anslutning, TLS, 401, 403, 400, 404, 405 m.fl. | Behandla inte felsvar som vanliga frågeresultat |
| JSON-RPC | error.code message data | Skilj mellan protokoll-, metod-, parameter- och auktoriseringsproblem |
| MCP-verktyg | result.isError och structuredContent | HTTP 200 kan ändå innebära ett fel |
| Affärsresultat | Verklig status, fullständighet, felorsak, nextAction | Mottaget eller redo betyder inte slutfört |
| Giltighet som fakta | executionReceipt citationEligible contentComplete | Innehåll som inte är giltigt som fakta används endast för lokalisering eller för att förklara luckor |
Vanliga HTTP-situationer
- 401: Bearer saknas eller är ogiltig; förnya eller auktorisera på nytt enligt det aktuella OAuth-flödet.
- 403: Grant, roll, vald resurs, källbehörighet, Origin eller konfiguration uppfyller inte kraven; försök inte kringgå det genom att skicka om förfrågan.
- 400: Meddelandet eller det versionshanterade kontraktet är ogiltigt, inklusive inkonsekvens mellan moderna huvuden och metadata.
- 404: Kontrollera exakt tjänstesökväg, protokollmetod och runtime-funktioner; byt inte ontologi-ID på måfå.
- 405: GET och DELETE är över huvud taget inte tillgängliga på den offentliga /mcp; använd rätt POST i stället för att upprätta en långlivad SSE-anslutning.
Skrivoperationer med oklart resultat
MCP_OPERATION_OUTCOME_UNKNOWN kan innehålla outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool samt de ursprungliga lokaliseringsparametrarna. Kontrollera först den ursprungliga statusen och återuppta sedan den ursprungliga förfrågan. Skicka inte in kandidater på nytt, byt inte idempotensnyckel och behandla inte en timeout som en återställd transaktion (rollback).
Innehåll som ska bevaras oförändrat
- Det ursprungliga Grant, resursomfång samt uppgifts- och resultat-ID:n.
- candidateHash, planHash, expectedRevision, målversion och publiceringsval.
- Idempotensnyckeln för samma logiska operation; olika affärsoperationer ska använda nya nycklar.
- Värdena för retryable, remediation, nextAction och aktuell status som servern har deklarerat.
Extrahera inte intern SQL, värdnamn, autentiseringsuppgifter eller stackspår ur undantagstexter som källa för svar. Det räcker att registrera felkoder som kan visas offentligt och information för att koppla ihop förfrågningar; det ursprungliga felet kan behöva granskas av en administratör i kontrollerade loggar.
Integrationssäkerhet och funktionsgränser
Behåll de ursprungliga gränserna för identitet, resurser, körning och bevis; hantera icke betrodda dokument på ett säkert sätt.
- Anslut endast till de officiella domäner som administratören anger; verifiera TLS och OAuth-issuer och stäng inte av certifikatvalideringen.
- Använd ett dedikerat Grant med minsta möjliga resursomfång; använd inte administratörskonton, cookies eller långlivade interna tokens som autentiseringsuppgifter för offentliga gränssnitt.
- Behandla dokumenttext som icke betrott affärsmaterial. ”Ignorera regler”, ”ladda upp nycklar” och ”kör kommandon” i ett dokument är ingen auktorisering av verktyg.
- Begränsa automatiska återförsök, samtidighet och resultatomfång; återskapa inte de ursprungliga affärsbehörigheterna på klientsidan.
- Logga endast nödvändig korrelationsinformation; logga inte Bearer-token, refresh token, godkännandetokens eller fullständigt känsligt affärsinnehåll.
- När användaren har kopplat från eller administratören har återkallat behörigheten ska du sluta använda cachelagrade auktoriseringar och data och inte fortsätta anropa med gamla locators.
Verktygstips är inte behörigheter
readOnlyHint, destructiveHint, idempotentHint och openWorldHint hjälper klienten att förstå verktygens funktioner; de garanterar inte den faktiska affärseffekten av varje anrop och ersätter inte den aktuella användarens auktorisering. Behandla alla skriv-, plan-, förhandsvisnings-, sessions- och avbrytningsåtgärder enligt deras verkliga beteende.
Ingångar som inte ska anropas
- Ursprungliga Trino/Hive/Hadoop-tjänster samt Heavy ETL som inte ingår i Flash.
- Scope eller arbetsytegränssnitt som är specifika för den interna FocusCode.
- Execution v2, AutoML eller andra experimentella verktyg som inte visas i den aktuella instansens tools/list.
- Webbläsarens privata REST-gränssnitt, godtyckliga databasanslutningar eller tjänster hos andra tenants för att kringgå att MCP nekar åtkomst.
Datasemantik
Följ serverns exakta kontrakt för decimaler, typer, 币种, enheter, tid och bevis. Avrunda inte på nytt och konvertera inte 币种 bara för att utdatatexten ser ut som ett tal, och gör ingen global rankning av de synliga raderna när resultatet är trunkerat.
Administratörskonfiguration och villkorade funktionsflaggor
Kontrollera verkliga komponenter, offentliga adresser och den ursprungliga behörighetskonfigurationen innan utökade funktioner aktiveras.
| Konfiguration | Syfte | Krav för lansering |
|---|---|---|
| datafocus.mcp.public-base-url | Officiell extern rotadress | OAuth-discovery, issuer, återanrop och omvänd proxy stämmer överens |
| datafocus.mcp.allowed-origins | Ytterligare godkända webbläsarursprung (origins) | Exakt konfiguration; utvidga inte till godtyckliga ursprung |
| datafocus.mcp.oauth.route-proof-secret | Dedikerad serverhemlighet för bevis vid grafroutning | Förvaras separat; använd inte en Bearer-token som nyckel |
| datafocus.mcp.analysis.tools.enabled | Interaktiva analysverktyg | Tillhörande data-, kunskaps- och behörighetstjänster är faktiskt tillgängliga |
| datafocus.mcp.analysis.report-tools.enabled | Beständiga rapportverktyg | Tillhörande lagring, worker och återställningskedja är tillgängliga |
| datafocus.mcp.analysis.apps.enabled | MCP Apps-visning | Klienten deklarerar stöd och kontrollerar den returnerade _meta |
| datafocus.mcp.authoring.enabled | Utkast- och modelleringskontrakt | De ursprungliga administratörs- och resursbehörigheterna behålls |
| datafocus.mcp.authoring.apply-enabled | Tillämpning av artefakter | Oföränderlig plan, ursprungligt godkännande och omvalidering av aktuell status |
| datafocus.mcp.ontology-published-query-enabled | Publicerade modeller och frågor | Verkliga committade versioner och auktorisering av källor |
| datafocus.mcp.ontology-candidate-query-enabled | Strukturerade kandidatfrågor | Ägarskap för kandidaten, exakt version och läsbehörighet |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Auktorisering för delegering av automatisk publicering | Giltig ursprunglig policy, förtroende för offentliga nycklar, budget och publiceringsrätt |
Namnen kommer från konfigurationen och implementationen i r56; om de kan aktiveras beror på tillhörande tjänster och de ursprungliga grindarna för lansering. Att bara ändra ett booleskt värde ersätter inte saknade processorer, databaser, valideringsbudgetar eller policyer. Om tilläggen för kunskapsinmatning och Pi-uppgifter syns avgörs av vilka komponenter som faktiskt är installerade.
Edge-proxy
Behåll Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name och godkänd Origin. Ställ in förfrågningskropp, timeout och TLS enligt tjänstens faktiska krav; vidarebefordra inte den offentliga /mcp till en administrationsport eller till en annan produkt.
Kontroller inför lansering
- Statusen för anonym discovery och skyddade anrop är som förväntat.
- Vanliga användare kan bara identifiera det som ingår i deras auktorisering; efter återkallad behörighet nekas efterföljande förfrågningar.
- Inbyggda Search-sessioner, SQL, originaltext och valfria rapporter ger alla verkliga resultat.
- Godkännanden och idempotent återställning för skriv- och publiceringsoperationer behåller ursprungligt beteende.
- Loggar och offentlig dokumentation innehåller inte privata nycklar, tokens, cookies, lösenord eller interna kunduppgifter.
Körbara klienter och anropsexempel
Verifiera meddelanden med den tillhörande minimala klienten; kringgå inte OAuth eller den aktuella auktoriseringen.
examples/flash_mcp.py är en minimal protokollklient som bara är beroende av Pythons standardbibliotek. Den loggar inte in, godkänner inget å användarens vägnar, anropar inte automatiskt verktyg som inte syns, stöder både moderna och äldre protokoll och avslutas på olika nivåer vid fel i HTTP, JSON-RPC eller verktyg. Token anges via processmiljön och skrivs inte in i skript eller dokumentationsfiler.
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_TOKENLäsning och frågor
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.jsonErsätt först platshållare som ONTOLOGY_ID och TABLE_RESOURCE_ID i förfrågningsfilen med de verkliga värden som den aktuella auktoriseringen har returnerat. Klienten vägrar att köra om platshållare påträffas. SQL-exemplet kräver att den medföljande CSV-filen har importerats med de ursprungliga kolumnnamnen; utan motsvarande schema kan det inte skickas in direkt.
Andra scenarier
- Affärsingång: använd --endpoint business och hämta ett nytt Grant för /mcp/business.
- Äldre klient: välj --protocol 2025-11-25, kör först initialize och anropa sedan med samma protokoll.
- Inbyggd dokumentation: läs de verkliga URI:erna med resources eller read-resource.
- Självtest offline: --self-test verifierar att moderna huvuden och metadata byggs korrekt, kräver ingen token och skickar inga förfrågningar till produktens server.
Exemplets avgränsningar
Klienten är startpunkten för protokollanslutning och genererar inte automatiskt modelleringskandidater, sparar inte frågor och svar och utför ingen publicering. Den skriver ut den ursprungliga JSON så att agenten i lagret ovanför kan kontrollera affärsstatusen; lova inte användaren att en fråga, rapport eller publicering är slutförd enbart utifrån processens slutkod.
Bädda in ontologins dialoggränssnitt
Bädda in dialogsidan för människor i affärsapplikationens frontend och behåll gränserna för inloggning och webbläsarsäkerhet.
<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 är ett exempel på tenant-ID och 1001 ett exempel på ontologi-ID; ersätt dem vid användning med verkliga koordinater du har behörighet till. En enskild ontologi kan anges via path eller en query som stöds; i läget all kan användaren med @ välja bland de ontologier som hen har åtkomst till. skillId skickas bara vidare; påstå inte utifrån det att orkestrering av skills redan kan köras.
Autentisering och domäner
Den nuvarande inbäddade sidan kräver en verklig DataFocus-inloggningssession och kontrollerar /uc/status. Cookies över flera webbplatser, SSO, CSP frame-ancestors och gatewaykonfiguration påverkar inbäddningen. Den accepterar inte att en MCP Bearer-token läggs i URL:en som en väg förbi inloggningen; externa outside-länkar som ännu inte är implementerade får inte konstrueras på egen hand utifrån designförslag.
Skillnaden mellan MCP och iframe
| Metod | Användare | Identitet och resultat |
|---|---|---|
| Remote MCP | Externa agenter eller tjänsteintegrationer | OAuth Grant och strukturerade verktygskvitton |
| Ontologidialog i iframe | Slutanvändare (människor) | Ursprunglig inloggningssession och dialoggränssnitt |
| MCP Apps | MCP-klienter med stöd för tillägget | Kontrollerade resurser och aktuella verktygsresultat, ingen ersättning för inloggning via en offentlig iframe |
Checklista för integrationsgodkännande
Visa att hela affärskedjan fungerar på en verklig instans, i stället för att bara bekräfta att gränssnittet returnerar 200.
- Discovery: hämta de versioner som faktiskt stöds, den aktuella verktygskatalogen och inbyggda resurser.
- Auktorisering: vanliga användare ser endast godkända ontologier och affärssystem; åtgärder utan scope nekas.
- Tabellstruktur: verkliga visningsnamn, kolumner, typer och behörigheter är fullständiga.
- SQL: kontroller av endimensionella, flerdimensionella, JOIN-, datum-, TopN- och trunkeringsfrågor motsvarar faktiska affärsdefinitioner.
- Kunskap: lokalisering, fullständig originaltext och giltighet som faktareferens stämmer överens; blandade frågor har både data- och dokumentunderlag.
- Search: kontrollerna av modell, init, förslag, resultat, stängning och buffertens fullständighet klaras.
- Valfri analys och rapportering: verklig status för flera grenar, sidbläddring, behörighetsändringar och avbrytande behåller det ursprungliga beteendet.
- Valfri modellering: kandidat, plan, ursprungligt godkännande, faktisk tillämpning och versionsfrågor kontrolleras steg för steg.
- Affärsåtgärder: publiceringshash, målversion, godkännande, idempotens och isolering mellan olika Grant kontrolleras.
- Återställning: efter en nätverkstimeout återställs det ursprungliga tillståndet; när källan uppdateras blir gamla lokaliseringar ogiltiga och nya frågor används.
Dokumentation av resultat
Dokumentera instansversion, användarroll, Grant-omfång, konfigurationsversion, faktiska åtgärder och resultat. Protokollklientens offline-självtest, förväntade offlinevärden för exempel-CSV, statisk JSON Schema-validering och verkligt funktionellt acceptanstest i drift märks var för sig. Dra inte slutsatsen att hela produkten är godkänd bara för att ett steg har godkänts.
Referensresurser och underhåll
Använd de fullständiga verktygsscheman som medföljer manualen och håll dem synkroniserade med instansens faktiska discovery-resultat.
| Resurser | Innehåll |
|---|---|
| reference/mcp-tool-catalog.json | Deklarerade indatascheman för 32 verktyg på ontologisidan och 8 på affärssidan; vissa verktyg har även det ursprungliga outputSchema |
| reference/locales.json | 21 valbara och 24 kompatibla locales samt UI-terminologi |
| reference/search-keywords.json | Statisk nyckelordskatalog för 17 uttryckligen angivna locales |
| reference/analysis-contract-manifest.json | Versionsbegränsningar för analys, grenar, fakta, kvitton och rapporter |
| examples/ | Syntetisk CSV, beskrivning av affärsdefinitioner, Top3-SQL, förväntade resultat och en minimal protokollklient |
Inbyggda beskrivningsresurser
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list och resources/read kräver att den aktuella användaren har motsvarande läsbehörighet för minst en av metadata, search operate eller etl operate. ETL-dokumentationen är en statisk referens mellan produkter; Flashs körbara funktioner är fortfarande begränsade till det som Flash uttryckligen rapporterar.
Extern protokollreferens
För MCP-protokollet och auktoriseringsbakgrunden, se de officiella specifikationerna: https://modelcontextprotocol.io/specification/2026-07-28/basic och https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. För den här produktens slutpunkter, verktyg och villkorade beteenden gäller implementationen i r56 och instansens aktuella discovery-resultat; allmänt protokollstöd får inte jämställas med att servern tillhandahåller alla valfria funktioner.
Uppgradering och underhåll
Vid uppgradering gör du om discovery av verktyg och versioner och jämför indatascheman, utdatakontrakt och konfiguration; ett gammalt Grant får inte automatiskt nya scope. Håll referenser, cache och kvitton bundna till källversionen, hämta kontexten på nytt när inkompatibla ändringar har bekräftats och tvinga inte in gamla lokaliseringar i ett nytt affärstillstånd.
Referens för verktygsparametrar: grundläggande verktyg och inbyggd Search
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfc_manual
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| names | array | Valfri eller villkorligt obligatorisk | Uttryckliga namn att slå upp, högst 32 per anrop. maxItems: 32 |
| action | string | Valfri eller villkorligt obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: list, read, keywords, functions, etl_requests |
| locale | string | Valfri eller villkorligt obligatorisk | Uttrycklig locale för den statiska referenskatalogen, inte standardspråk för frågor. |
| uri | string | Valfri eller villkorligt obligatorisk | URI för inbyggda resurser som listas av det aktuella verktyget. 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 | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| data | object | Valfri eller villkorligt obligatorisk | Ursprunglig payload för åtgärden; se tabellen över funktionsidentifiering och åtgärdsfält. |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| data | object | Valfri eller villkorligt obligatorisk | Ursprunglig payload för åtgärden; se tabellen över funktionsidentifiering och åtgärdsfält. |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: capabilities |
dfc_ontologies
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| pageSize | integer | Valfri eller villkorligt obligatorisk | Antal poster per sida; enligt schemats gräns. minimum: 1; maximum: 100 |
| page | integer | Valfri eller villkorligt obligatorisk | Sidnummer, börjar på 1. minimum: 1 |
dfc_ontology_resources
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| resourceTypes | array | Valfri eller villkorligt obligatorisk | Uppsättning resurstyper som ska returneras. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| pageSize | integer | Valfri eller villkorligt obligatorisk | Antal poster per sida; enligt schemats gräns. minimum: 1; maximum: 100 |
| page | integer | Valfri eller villkorligt obligatorisk | Sidnummer, börjar på 1. minimum: 1 |
Referens för verktygsparametrar: tabeller, graf och kunskap
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfc_ontology_graph
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| relationTypes | array | Valfri eller villkorligt obligatorisk | Filter för relationstyp. |
| depth | integer | Valfri eller villkorligt obligatorisk | Djup för granntraversering. minimum: 1; maximum: 3 |
| sourceTypes | array | Valfri eller villkorligt obligatorisk | Filter för källtyp. |
| query | object | Valfri eller villkorligt obligatorisk | Frågetext, eller exakt versionerat frågeobjekt motsvarande action. |
| limit | integer | Valfri eller villkorligt obligatorisk | Högsta antal resultat som returneras. minimum: 1; maximum: 100 |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| nodeKey | string | Valfri eller villkorligt obligatorisk | Nodnyckel kopierad från faktiskt grafresultat. |
| keyword | string | Valfri eller villkorligt obligatorisk | Nyckelord för graflokalisering, inte syntaxen för nyckelordsfrågor. |
| nodeTypes | array | Valfri eller villkorligt obligatorisk | Filter för nodtyp. |
dfc_ontology_query
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| routeLocators | array | Valfri eller villkorligt obligatorisk | Den typade routningslokalisering som servern har utfärdat, kopierad i sin helhet. maxItems: 20 |
| topK | integer | Valfri eller villkorligt obligatorisk | Högsta antal kandidater vid återhämtning (recall); bevisar inte fullständig täckning. minimum: 1; maximum: 20 |
| queryMode | string | Valfri eller villkorligt obligatorisk | Läge för bevisfrågor, väljs enligt verktygets enum. enum: vector, hybrid, graph |
| fanoutPlan | object | Valfri eller villkorligt obligatorisk | Begränsad sökplan för grenar, enligt det nästlade schemat. |
| structuredPlan | object | Valfri eller villkorligt obligatorisk | Plan för en fullständig dokumenttabell, bunden till serverns kontrakt; inte SQL. |
| knowledgeIds | array | Valfri eller villkorligt obligatorisk | Kunskapsbas-ID från faktiska knowledgeBindings. |
| query | string | Obligatorisk | Frågetext, eller exakt versionerat frågeobjekt motsvarande action. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
dfc_knowledge_search
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| topK | integer | Valfri eller villkorligt obligatorisk | Högsta antal kandidater vid återhämtning (recall); bevisar inte fullständig täckning. minimum: 1; maximum: 20 |
| minScore | number | Valfri eller villkorligt obligatorisk | Lägsta matchpoäng. minimum: 0; maximum: 1 |
| knowledgeIds | array | Valfri eller villkorligt obligatorisk | Kunskapsbas-ID från faktiska knowledgeBindings. |
| query | string | Obligatorisk | Frågetext, eller exakt versionerat frågeobjekt motsvarande action. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| assetIds | array | Valfri eller villkorligt obligatorisk | Asset-ID:n för dokument som för närvarande är tillåtna. |
| retrievalStrategy | string | Valfri eller villkorligt obligatorisk | Sökstrategi som faktiskt stöds. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| qdrantId | string / integer | Valfri eller villkorligt obligatorisk | Indexidentifierare som returnerats vid faktisk lokalisering. |
| pageNo | integer | Valfri eller villkorligt obligatorisk | Faktiskt sidnummer i dokumentet eller i sidnumreringen. |
| evidenceId | string | Valfri eller villkorligt obligatorisk | Bevis-ID som returnerats för samma kunskapslokalisering. |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: chunk, document, page_context |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| documentId | string / integer | Valfri eller villkorligt obligatorisk | Dokument-ID för samma lokalisering. |
| radius | integer | Valfri eller villkorligt obligatorisk | Intilliggande sidintervall. minimum: 0; maximum: 3 |
| chunkId | string | Valfri eller villkorligt obligatorisk | Faktiskt chunk-ID för samma lokalisering. |
dfc_table
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| maxRows | integer | Valfri eller villkorligt obligatorisk | Högsta antal rader som returneras; inte ett rankningsomfång för klienten. minimum: 1; maximum: 200 |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: detail, query |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| id | string | Valfri eller villkorligt obligatorisk | Verkligt tabellresurs-ID, inte fysiskt namn eller visningsnamn. |
| sql | string | Valfri eller villkorligt obligatorisk | En enda skrivskyddad Doris-SQL-sats inom ontologins omfång, med explicita utdatakolumner. |
Referens för verktygsparametrar: analys och rapportering
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfc_analysis_ask
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| question | string | Obligatorisk | Fråga på naturligt språk eller kompatibel uppföljningsfråga. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| language | string | Valfri eller villkorligt obligatorisk | Explicit locale för svar eller fråga; om den utelämnas gäller respektive verktygs regler. |
| sessionId | string | Valfri eller villkorligt obligatorisk | Verklig sessionslokalisering under samma Grant. |
dfc_analysis_refine
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| branchId | string | Valfri eller villkorligt obligatorisk | Strukturerad grenlokalisering utfärdad av servern. |
| resultId | string | Obligatorisk | Lokalisering av det ursprungliga analysresultatet. |
| question | string | Valfri eller villkorligt obligatorisk | Fråga på naturligt språk eller kompatibel uppföljningsfråga. |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| change | object | Valfri eller villkorligt obligatorisk | Ändring på naturligt språk eller typad filter_patch. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| language | string | Valfri eller villkorligt obligatorisk | Explicit locale för svar eller fråga; om den utelämnas gäller respektive verktygs regler. |
| sessionId | string | Obligatorisk | Verklig sessionslokalisering under samma Grant. |
| expectedRevision | integer | Obligatorisk | Versionsvillkor för det ursprungliga resultatet eller affärshuvudet; kan vara null när frågan skapas. minimum: 1 |
| visualId | string | Valfri eller villkorligt obligatorisk | Visualiseringslokalisering bunden till grenen. |
dfc_analysis_page
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| branchId | string | Obligatorisk | Strukturerad grenlokalisering utfärdad av servern. |
| resultId | string | Obligatorisk | Lokalisering av det ursprungliga analysresultatet. |
| pageNo | integer | Obligatorisk | Faktiskt sidnummer i dokumentet eller i sidnumreringen. minimum: 1; maximum: 10000 |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| pageSize | integer | Obligatorisk | Antal poster per sida; enligt schemats gräns. minimum: 1; maximum: 100 |
| sessionId | string | Obligatorisk | Verklig sessionslokalisering under samma Grant. |
| expectedRevision | integer | Obligatorisk | Versionsvillkor för det ursprungliga resultatet eller affärshuvudet; kan vara null när frågan skapas. minimum: 1 |
dfc_analysis_result_get
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| resultId | string | Obligatorisk | Lokalisering av det ursprungliga analysresultatet. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| sessionId | string | Obligatorisk | Verklig sessionslokalisering under samma Grant. |
dfc_analysis_cancel
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| resultId | string | Obligatorisk | Lokalisering av det ursprungliga analysresultatet. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| sessionId | string | Obligatorisk | Verklig sessionslokalisering under samma Grant. |
dfc_analysis_close
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| sessionId | string | Obligatorisk | Verklig sessionslokalisering under samma Grant. |
dfc_report_create
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| goal | string | Obligatorisk | Rapportens analysmål. |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| language | string | Valfri eller villkorligt obligatorisk | Explicit locale för svar eller fråga; om den utelämnas gäller respektive verktygs regler. |
| title | string | Valfri eller villkorligt obligatorisk | Valfri rapportrubrik. |
dfc_report_status
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| reportId | string | Obligatorisk | Lokalisering av en beständig rapport för det aktuella Grant. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
dfc_report_cancel
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| reportId | string | Obligatorisk | Lokalisering av en beständig rapport för det aktuella Grant. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
Referens för verktygsparametrar: modellering och agentuppgifter
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfc_ontology_agent
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| mode | string | Valfri eller villkorligt obligatorisk | QUERY eller AUTHORING; funktionerna auktoriseras var för sig. enum: QUERY, AUTHORING |
| instruction | string | Valfri eller villkorligt obligatorisk | Användarens kravtext; måste vara densamma i context och submit. maxLength: 16000 |
| idempotencyKey | string | Valfri eller villkorligt obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. maxLength: 128 |
| action | string | Obligatorisk | Åtgärdens namn. Används enligt aktuell enum tillsammans med de parametrar som hör till respektive åtgärd. enum: start, status, cancel |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| runId | string | Valfri eller villkorligt obligatorisk | Ursprungligt uppgifts-ID för samma ontologi och Grant. |
| contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
Rotobjektet för verktygets indata har inga fält; använd ett tomt arguments-objekt.
dfc_artifact_context
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Valfri eller villkorligt obligatorisk | Typ av resursomfång i det faktiska artefaktkontraktet. |
| ontologyId | string | Valfri eller villkorligt obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| projectId | string | Valfri eller villkorligt obligatorisk | Aktuellt auktoriserat projekt-ID. |
| artifactId | string | Valfri eller villkorligt obligatorisk | Verkligt ID för den befintliga artefakt som redigeras. |
| instruction | string | Obligatorisk | Användarens kravtext; måste vara densamma i context och submit. |
| variables | object | Valfri eller villkorligt obligatorisk | Variabelobjekt enligt det returnerade kontraktet. |
| previewInput | object | Valfri eller villkorligt obligatorisk | Begränsade indata för förhandsvisning enligt kontraktet. |
| viewport | object | Valfri eller villkorligt obligatorisk | Visningsområde (viewport) som det ursprungliga kontraktet kräver. |
dfc_ontology_table_schema
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| sourceAssetRef | string | Obligatorisk | Registrerad strukturerad tillgångsreferens, t.ex. table:123. |
| fields | array | Obligatorisk | Fält i den aktuella källan samt valfria explicita typdeklarationer. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| proposalId | string | Obligatorisk | Ursprungligt kandidat-ID som skapades med det aktuella Grant. |
| candidateHash | string | Obligatorisk | Exakt hash för den ursprungliga kandidaten på servern. |
| previewInput | object | Obligatorisk | Begränsade indata för förhandsvisning enligt kontraktet. |
dfc_artifact_status
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| proposalId | string | Valfri eller villkorligt obligatorisk | Ursprungligt kandidat-ID som skapades med det aktuella Grant. |
| planId | string | Valfri eller villkorligt obligatorisk | ID för den oföränderliga tillämpningsplanen. |
dfc_artifact_plan
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| proposalId | string | Obligatorisk | Ursprungligt kandidat-ID som skapades med det aktuella Grant. |
| candidateHash | string | Obligatorisk | Exakt hash för den ursprungliga kandidaten på servern. |
| expectedTargetVersion | integer | Obligatorisk | Villkor om den aktuella verkliga målversionen. minimum: 0 |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
dfc_artifact_apply
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| planId | string | Obligatorisk | ID för den oföränderliga tillämpningsplanen. |
| planHash | string | Obligatorisk | Hash som returnerades för den ursprungliga planen. |
| approvalToken | string | Obligatorisk | Godkännandematerial som utfärdats av den ursprungliga servern; får inte genereras på egen hand. |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
dfc_artifact_submit
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| Konfiguration 1 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Konfiguration 1 / scopeType | string | Valfri eller villkorligt obligatorisk | Typ av resursomfång i det faktiska artefaktkontraktet. |
| Konfiguration 1 / ontologyId | string | Valfri eller villkorligt obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| Konfiguration 1 / projectId | string | Valfri eller villkorligt obligatorisk | Aktuellt auktoriserat projekt-ID. |
| Konfiguration 1 / artifactId | string | Valfri eller villkorligt obligatorisk | Verkligt ID för den befintliga artefakt som redigeras. |
| Konfiguration 1 / instruction | string | Obligatorisk | Användarens kravtext; måste vara densamma i context och submit. |
| Konfiguration 1 / variables | object | Valfri eller villkorligt obligatorisk | Variabelobjekt enligt det returnerade kontraktet. |
| Konfiguration 1 / previewInput | object | Valfri eller villkorligt obligatorisk | Begränsade indata för förhandsvisning enligt kontraktet. |
| Konfiguration 1 / viewport | object | Valfri eller villkorligt obligatorisk | Visningsområde (viewport) som det ursprungliga kontraktet kräver. |
| Konfiguration 1 / contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. |
| Konfiguration 1 / contextHash | string | Obligatorisk | Fullständig kontexthash som returnerats av context. |
| Konfiguration 1 / baseArtifactHash | string | Obligatorisk | Hash för basartefakten som returnerats av context. |
| Konfiguration 1 / baseArtifactVersion | integer | Obligatorisk | Basversion som returnerats av context. minimum: 0 |
| Konfiguration 1 / candidate | object | Obligatorisk | Kandidatobjekt som överensstämmer med det aktuella returnerade kontraktet. |
| Konfiguration 1 / clientRequestId | string | Obligatorisk | Klientens idempotensnyckel, som används stabilt för den aktuella kandidatförfrågan. |
| Konfiguration 2 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: ONTOLOGY_RELEASE |
| Konfiguration 2 / contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. 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 |
| Konfiguration 2 / ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| Konfiguration 2 / candidateHash | string | Obligatorisk | Exakt hash för den ursprungliga kandidaten på servern. |
| Konfiguration 2 / workspaceId | string | Obligatorisk | Faktiska arbetsytekoordinater för kandidaten. |
| Konfiguration 2 / workspaceRevision | string | Obligatorisk | Exakt kandidatversion; använd inte latest. |
| Konfiguration 2 / releases | object | Obligatorisk | Exakt versionsval enligt kontraktet för ontologipublicering. |
| Konfiguration 2 / selection | object | Obligatorisk | Anger endast uttryckliga koordinater för affärsurvalet, inte behörigheter eller bevis på slutförande. |
| Konfiguration 2 / idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| Konfiguration 3 / Konfiguration 1 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: ONTOLOGY_RELEASE |
| Konfiguration 3 / Konfiguration 1 / contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. enum: ontology-workspace-create-mcp-submit-v1 |
| Konfiguration 3 / Konfiguration 1 / ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| Konfiguration 3 / Konfiguration 1 / workspaceId | string | Obligatorisk | Faktiska arbetsytekoordinater för kandidaten. |
| Konfiguration 3 / Konfiguration 1 / resources | array | Obligatorisk | Ursprunglig modelldeklaration kompilerad på servern. minItems: 1 |
| Konfiguration 3 / Konfiguration 1 / idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| Konfiguration 3 / Konfiguration 2 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: ONTOLOGY_RELEASE |
| Konfiguration 3 / Konfiguration 2 / contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. enum: ontology-workspace-create-mcp-submit-v2 |
| Konfiguration 3 / Konfiguration 2 / ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| Konfiguration 3 / Konfiguration 2 / workspaceId | string | Obligatorisk | Faktiska arbetsytekoordinater för kandidaten. |
| Konfiguration 3 / Konfiguration 2 / resources | array | Obligatorisk | Ursprunglig modelldeklaration kompilerad på servern. minItems: 1 |
| Konfiguration 3 / Konfiguration 2 / idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| Konfiguration 3 / Konfiguration 2 / releaseSelections | object | Obligatorisk | Exakt releaseId för varje publicerad referens samt dess beroendehölje. |
| Konfiguration 4 / artifactType | string | Obligatorisk | Artefakt- eller ontologipubliceringstyp som faktiskt är aktiverad. enum: ONTOLOGY_RELEASE |
| Konfiguration 4 / contractVersion | string | Obligatorisk | Måste vara en exakt kontraktsversion som faktiskt stöds. enum: ontology-initial-activation-retirement-submit-v1 |
| Konfiguration 4 / ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| Konfiguration 4 / domainRid | string | Obligatorisk | Verklig RID för affärsdomänen. |
| Konfiguration 4 / consumerScopes | array | Obligatorisk | Exakta konsumentscope som servern tillåter. minItems: 1; maxItems: 256 |
| Konfiguration 4 / idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
Referens för verktygsparametrar: kunskapsinmatning och omfång
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfc_ontology_knowledge_input_propose
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| request | object | Obligatorisk | Ursprunglig förfrågan med affärsindata; enligt det fullständiga nästlade schemat. |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. minLength: 1; maxLength: 128 |
Det här verktyget har dessutom ett inbyggt outputSchema. Kontrollera utdatans fullständighet, status och de auktoriseringsfält som uttryckligen är false; tolka inte själv resultatet som mer slutfört än det är.
dfc_ontology_knowledge_input_preview
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. minLength: 1; maxLength: 128 |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
Det här verktyget har dessutom ett inbyggt outputSchema. Kontrollera utdatans fullständighet, status och de auktoriseringsfält som uttryckligen är false; tolka inte själv resultatet som mer slutfört än det är.
dfc_ontology_knowledge_question_submit
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| questionRevision | $ref | Obligatorisk | Exakt version av frågan som ska bekräftas. |
| idempotencyKey | $ref | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. |
| originalInputKey | $ref | Obligatorisk | Idempotensnyckel motsvarande den ursprungliga kunskapsinmatningen. |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. |
| validUntil | $ref | Obligatorisk | Slutpunkt för frågans giltighetsfönster, UTC-tid. |
| expectedRevision | oneOf | Obligatorisk | Versionsvillkor för det ursprungliga resultatet eller affärshuvudet; kan vara null när frågan skapas. |
| validFrom | $ref | Obligatorisk | Startpunkt för frågans giltighetsfönster, UTC-tid. |
Det här verktyget har dessutom ett inbyggt outputSchema. Kontrollera utdatans fullständighet, status och de auktoriseringsfält som uttryckligen är false; tolka inte själv resultatet som mer slutfört än det är.
dfc_ontology_business_scope_initialize
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| domainRevisionId | string | Obligatorisk | Exakt version av affärsdomänen. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Obligatorisk | Idempotensnyckel som återanvänds stabilt för samma logiska åtgärd. minLength: 1; maxLength: 128 |
| businessSystemId | string | Obligatorisk | Verkligt affärssystem-ID. minLength: 1 |
| ontologyId | string | Obligatorisk | Verkligt ontologi-ID inom den här auktoriseringen, bevaras som sträng. minLength: 1 |
| domainRid | string | Obligatorisk | Verklig RID för affärsdomänen. minLength: 1; maxLength: 128 |
Det här verktyget har dessutom ett inbyggt outputSchema. Kontrollera utdatans fullständighet, status och de auktoriseringsfält som uttryckligen är false; tolka inte själv resultatet som mer slutfört än det är.
Referens för verktygsparametrar: affärsarbetsytan
Fullständiga namn och indatafält, grupperade per verktyg.
Tabellerna nedan är en läsreferens för indatafälten i de aktuella r56-verktygen. Fullständiga nästlade typer, oneOf, villkorligt obligatoriska fält, mönsterbegränsningar och vissa utdatascheman finns i reference/mcp-tool-catalog.json; läs ändå tools/list för det aktuella Grant innan du skickar in slutgiltigt. ”Valfri” i tabellen tar inte bort kraven från åtgärdens interna validering.
dfb_systems
Rotobjektet för verktygets indata har inga fält; använd ett tomt arguments-objekt.
dfb_system_describe
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillåts av det aktuella affärs-Grant. |
dfb_query
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillåts av det aktuella affärs-Grant. |
| queryKey | string | Obligatorisk | Publicerad frågenyckel som returnerats av describe. |
| objectKey | string | Valfri eller villkorligt obligatorisk | Publicerad objektnyckel. |
| pageSize | integer | Valfri eller villkorligt obligatorisk | Antal poster per sida; enligt schemats gräns. minimum: 1; maximum: 100 |
| page | integer | Valfri eller villkorligt obligatorisk | Sidnummer, börjar på 1. minimum: 1 |
| state | string | Valfri eller villkorligt obligatorisk | Filter för affärsstatus eller serverstatus. |
dfb_record
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| recordId | string / integer | Obligatorisk | ID för en affärspost som du för närvarande har behörighet att läsa. |
| systemId | string / integer | Obligatorisk | System-ID som tillåts av det aktuella affärs-Grant. |
dfb_work_items
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| systemId | string / integer | Obligatorisk | System-ID som tillåts av det aktuella affärs-Grant. |
dfb_action_plan
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| expectedRecordVersion | integer | Valfri eller villkorligt obligatorisk | Målpostens aktuella version för optimistisk låsning. minimum: 1 |
| systemId | string / integer | Obligatorisk | System-ID som tillåts av det aktuella affärs-Grant. |
| commandType | string | Obligatorisk | Kommandotyp enligt det publicerade kontraktet. |
| canonicalIrHash | string | Obligatorisk | Hash för den aktuella publicerade kanoniska IR. |
| releaseId | string / integer | Obligatorisk | Verkligt ID för den publicerade kontraktsversionen. |
| payload | object | Obligatorisk | Payload som överensstämmer med det aktuella kommandokontraktet i describe. |
| releaseHash | string | Obligatorisk | Hash för det faktiska publicerade kontraktet. |
| targetRecordId | string / integer | Valfri eller villkorligt obligatorisk | Verklig målpost som ska åtgärdas. |
| agentManifestHash | string | Obligatorisk | Hash för det faktiska manifestet över agentens funktioner. |
| planIdempotencyKey | string | Obligatorisk | Stabil idempotensnyckel för affärsplanen. |
dfb_action_status
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| actionPlanId | string / integer | Obligatorisk | ID för en åtgärdsplan som ägs av det aktuella affärs-Grant. |
dfb_action_execute
| Parameter | Typ | Krav | Betydelse och omfång |
|---|---|---|---|
| approvalToken | string | Valfri eller villkorligt obligatorisk | Godkännandematerial som utfärdats av den ursprungliga servern; får inte genereras på egen hand. |
| actionPlanId | string / integer | Obligatorisk | ID för en åtgärdsplan som ägs av det aktuella affärs-Grant. |