Manuel d'intégration Agent et MCP d'OT Flash
Protocole, autorisation, contrats d'outils et flux d'appel complet
Créez des applications de données et de connaissances traçables à l'aide du Remote MCP public d'OT Flash r56. Ce manuel présente OAuth, les messages de protocole, la référence des paramètres de tous les outils déclarés, les règles de preuve, les capacités conditionnelles et les procédures de récupération, avec des exemples de clients exécutables et de données synthétiques.
Développeurs d'Agents, ingénieurs d'intégration et administrateurs
Les exemples fournis conservent les noms de champs affichés en chinois. La traduction de la langue de l'interface et du texte explicatif ne modifie pas les noms de tables, de colonnes, les valeurs d'énumération, les noms d'outils ni les champs de protocole réels.
Table des matières
- 1Périmètre d'accès des Agents et critères d'achèvement
- 2Connexion rapide et découverte des capacités
- 3Découverte, enregistrement et autorisation OAuth
- 4Scopes, frontières des ressources et permissions en temps réel
- 5Messages HTTP et MCP modernes
- 6Compatibilité des clients à l'ancien protocole
- 7Choisir les bons outils et canaux de preuve
- 8Ressources d'ontologie et types d'identifiants
- 9Contrat de requête et de structure pour les tables Doris
- 10Top3 multidimensionnel et gestion de la troncature
- 11Recherche de connaissances : texte intégral et éligibilité des preuves
- 12Modèle Search natif et sessions
- 13Conventions de langue et de région
- 14Analyse fusionnée et résultats interactifs
- 15Rapports visuels persistants et Apps MCP
- 16Artefacts : brouillon, aperçu, plan et application
- 17Contrat de création et de publication des candidats d'ontologie
- 18Modèle publié, requêtes sur les candidats et fermeture des références
- 19Délégation de tâches à l'agent d'ontologie
- 20Espace de travail métier MCP
- 21Entrées de connaissances métier et questions à confirmer
- 22Réponses, erreurs et nouvelles tentatives sûres
- 23Sécurité d'intégration et limites de capacité
- 24Câblage administrateur et options conditionnelles
- 25Client exécutable et exemples d'appel
- 26Intégration de l'interface de dialogue d'ontologie
- 27Liste de contrôle de validation de l'intégration
- 28Ressources de spécification et maintenance
- 29Référence des paramètres d'outils : base et Search natif
- 30Référence des paramètres d'outils : tables, graphe et connaissances
- 31Référence des paramètres d'outils : analyses et rapports
- 32Référence des paramètres d'outils : modélisation et tâches d'origine
- 33Référence des paramètres d'outils : saisie des connaissances et périmètre
- 34Référence des paramètres d'outils : espace de travail métier
Périmètre d'accès des Agents et critères d'achèvement
Choisissez le point d'entrée d'autorisation et menez à bien requêtes, collecte de preuves ou écritures contrôlées en vous fondant sur les reçus du serveur.
OT Flash r56 expose aux Agents externes des capacités de données et de connaissances dans le périmètre de l'ontologie via Remote MCP, et fournit un point d'entrée distinct pour l'espace de travail métier. Un Agent doit déterminer le travail exécutable à partir du tools/list réel, de l'inputSchema, des scopes OAuth et des permissions actuelles sur les ressources ; il ne peut pas déduire d'un manuel statique qu'un déploiement a déjà activé toutes les fonctions optionnelles.
| Point d'entrée | Finalité | Limites |
|---|---|---|
| /mcp | Ontologie, tables de données, connaissances documentaires, Search natif ainsi que l'analyse et la modélisation à ouverture conditionnelle | Intersection entre les permissions de l'utilisateur actuel et les ressources accordées par cette autorisation |
| /mcp/business | Découverte des systèmes métier, requêtes, plans d'action, statut et exécution | Autorisation propre à chaque système métier et contrat de publication |
| Page intégrée de l'agent d'ontologie | Dialoguer avec l'ontologie dans une interface humaine | Dépend d'une session de connexion réelle ; ce n'est pas un point d'entrée permettant d'obtenir un Token MCP sans connexion |
Classification des capacités
- Lecture de base : ontologie et ressources, positionnement dans le graphe, recherche de connaissances et texte intégral, détails des tables autorisées et Doris SQL.
- Délégation indépendante : dfc_search requiert search:operate et continue d'appliquer les permissions d'origine de l'utilisateur et du modèle.
- Ouverture conditionnelle : analyse, rapports persistants, brouillons et application d'artefacts, requêtes sur le modèle d'ontologie et tâches déléguées à un Agent.
- Capacités indisponibles : le dfc_etl de Flash se contente de rapporter les capabilities et ne fournit pas d'exécution Heavy ETL. AutoML et les entrées d'espaces de travail FocusCode internes ne font pas partie de l'API publique de Flash décrite dans ce manuel.
Critères d'achèvement
La lecture d'un fait exige un reçu réel et exploitable de requête ou de texte intégral ; la génération d'un candidat doit préciser qu'il n'est pas encore appliqué ; la publication exige un véritable reçu APPLIED ; l'annulation doit distinguer la demande de la confirmation. Le texte d'une réponse, un HTTP 200, l'acceptation par un outil ou la mention « terminé » du modèle ne prouvent pas à eux seuls le succès d'une opération métier.
Le fichier reference/mcp-tool-catalog.json fourni est une référence hors ligne des déclarations de r56 ; il contient les définitions activées sous condition et ne constitue le tools/list en temps réel d'aucun utilisateur. Le catalogue complet comprend 28 outils cœur d'ontologie, 4 extensions conditionnelles de contrôleurs et 8 outils côté métier, ce qui ne signifie pas que tous sont ouverts par défaut.
Connexion rapide et découverte des capacités
Commencez par le domaine officiel de l'instance et découvrez les outils réellement disponibles avec des privilèges minimaux.
- Obtenez auprès de l'administrateur l'adresse racine officielle en HTTPS ainsi que l'ontologie ou le système métier à consulter. N'utilisez pas les domaines d'exemple de la documentation pour appeler des systèmes métier réels.
- Configurez l'adresse du serveur MCP comme https://flash.example.com/mcp ; l'espace de travail métier utilise /mcp/business sur le même domaine.
- Déclenchez la connexion et l'autorisation OAuth selon la prise en charge du client et vérifiez les ressources et les scopes ; ne transmettez jamais de nom d'utilisateur ni de mot de passe au MCP.
- Effectuez la découverte ou l'initialisation propre à la génération de protocole utilisée, puis lisez tools/list et les descriptions des ressources.
- Commencez par une petite requête en lecture seule pour vérifier les résultats structurés et les erreurs avant d'exécuter l'objectif de l'utilisateur.
Fragment de configuration client
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Ce fragment illustre l'intention de configuration de l'adresse du serveur ; la structure du fichier de configuration et la prise en charge d'OAuth dépendent du client. N'inscrivez jamais d'access_token, refresh_token, Cookie ou mot de passe administrateur réels dans des fichiers publics.
Découverte des protocoles modernes
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": {}
}
}
}Vérifications avant intégration
- L'adresse racine des ressources, l'émetteur OAuth et l'adresse externe du proxy inverse sont cohérentes.
- Le client prend en charge la génération de protocole correspondante au lieu d'envoyer systématiquement initialize au point d'entrée du nouveau protocole.
- L'autorisation actuelle est liée à l'ontologie ou au système métier requis.
- Le Token est valide et les nouveaux scopes optionnels ont été expressément autorisés.
Découverte, enregistrement et autorisation OAuth
Utilisez le code d'autorisation et PKCE ; n'exposez pas les identifiants de connexion du produit à l'Agent.
| Point de terminaison | Méthode | Rôle |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Découverte des ressources MCP de l'ontologie |
| /.well-known/oauth-protected-resource/mcp | GET | Découverte compatible avec les chemins de ressources de l'ontologie |
| /.well-known/oauth-protected-resource/mcp/business | GET | Découverte des ressources MCP métier |
| /.well-known/oauth-authorization-server | GET | Métadonnées du serveur d'autorisation |
| /oauth/register | POST JSON | Enregistrement dynamique d'un public client |
| /oauth/authorize | GET ou formulaire POST | Connexion, sélection des ressources et confirmation de l'autorisation |
| /oauth/token | POST form | Échange du code d'autorisation et rotation du refresh token |
| /oauth/revoke | POST form | Révocation du Token |
| /oauth/grants | GET | Affichage des connexions autorisées par l'utilisateur connecté |
| /oauth/grants/revoke | POST form | Révocation de la connexion selon le flux de la page d'origine |
Ordre d'autorisation
- Lisez les métadonnées des ressources protégées et celles du serveur d'autorisation. Pour une requête sans Token, la réponse 401 et son en-tête WWW-Authenticate indiquent l'adresse de découverte des ressources.
- Enregistrez ou utilisez l'identité du client. Dans r56, l'enregistrement dynamique d'un public client utilise token_endpoint_auth_method=none ; un secret client ne peut pas remplacer PKCE.
- Générez un state et un code_verifier aléatoires, puis calculez le code_challenge S256.
- Ouvrez l'adresse authorize indiquée par les métadonnées en transmettant response_type=code, client_id, un redirect_uri exact, scope, resource, state, code_challenge et code_challenge_method=S256.
- L'utilisateur se connecte à DataFocus et choisit l'ontologie ou le système métier. Le client ne peut pas présélectionner des ressources auxquelles l'utilisateur n'a pas accès.
- Recevez le rappel, vérifiez le state et l'émetteur ; échangez le code d'autorisation avec le code_verifier d'origine.
- N'utilisez l'access_token que pour l'authentification Bearer MCP. Le rafraîchissement suit le flux OAuth d'origine ; conservez de manière sécurisée le refresh_token issu de la rotation.
Exemple d'enregistrement
{
"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"]
}Le rappel des clients Web utilise HTTPS ; les clients natifs peuvent utiliser une adresse de bouclage prise en charge. L'autorisation comme l'échange de Token exigent une correspondance exacte avec le rappel enregistré. Un Grant correspond à une protected resource ; ne mélangez pas les scopes d'ontologie et ceux de l'espace de travail métier dans une même connexion.
Cycle de vie des Tokens
Par défaut, le serveur r56 fixe l'access token à 3600 secondes, le refresh token à 2592000 secondes et le code d'autorisation à 300 secondes ; le déploiement peut remplacer ces valeurs. Le client doit s'appuyer sur expires_in de la réponse Token et sur les erreurs réelles, sans coder en dur les valeurs par défaut. Mettez à jour le Token après rafraîchissement ; la révocation d'un rôle, d'une permission de ressource ou d'un Grant entraîne le rejet des appels suivants.
Scopes, frontières des ressources et permissions en temps réel
Les scopes délèguent des permissions existantes ; ils n'accordent aucune élévation de rôle et ne partagent pas l'état métier entre Grants.
| Scope | Capacités typiques | Contraintes importantes |
|---|---|---|
| ontology.metadata:read | Ontologie, ressources, structure des tables | L'ontologie et les tables doivent figurer dans l'autorisation et dans le périmètre actuellement lisible |
| ontology.graph:read | Recherche dans le graphe et voisins | Renvoie des informations de positionnement, pas des preuves factuelles |
| ontology.knowledge:read | Positionnement des connaissances et texte intégral | Conserve les permissions d'origine de la base de connaissances et des documents |
| ontology.table:query | SQL des tables d'ontologie et requêtes de modèles publiés | La requête de table nécessite aussi le scope metadata ; la source réelle et les permissions de colonnes restent en vigueur |
| search:operate | Modèle natif par mots-clés et sessions | Délégation explicite indépendante, exécutée selon les permissions d'origine sur le modèle et sur les tables et colonnes de l'utilisateur |
| etl:operate | Capabilities Flash ETL | Heavy ETL non disponible |
| authoring.contract:read | Contrats de modélisation à ouverture conditionnelle | Nécessitent aussi l'activation de la fonction et les ressources associées |
| authoring.artifact:read | Lecture des candidats, plans, etc. dans le cadre de l'autorisation actuelle | Liée au principal d'origine, au Grant et aux ressources |
| authoring.artifact:draft | Soumission de candidats, aperçu, etc. | N'autorise ni l'exécution ni la publication |
| authoring.artifact:apply | Plan et application contrôlés | Nécessite toujours le rôle métier, les politiques et les approbations d'origine |
| execution.script:draft | Brouillons de scripts spécifiques | N'autorise pas l'exécution réelle de scripts |
| datasource.http:read / draft / test / import | Capacités d'artefacts de source de données HTTP à ouverture conditionnelle | Activation distincte pour chaque élément et permissions d'origine |
Exigences combinées de lecture
dfc_table detail requiert ontology.metadata:read ; query requiert en plus ontology.table:query. dfc_ontology_query requiert les deux scopes de lecture graph et knowledge. dfc_knowledge_search/detail requiert knowledge. published_model/published_query relèvent de table:query ; candidate_query nécessite en outre authoring.artifact:read. Les outils d'analyse vérifient aussi les scopes de preuve autorisés ; les rapports persistants exigent metadata et table query.
Ne figez pas les autorisations par défaut
Dans r56, l'ensemble de scopes d'ontologie par défaut inclut table query ; Search et ETL sont des délégations explicites. En dernier ressort, les métadonnées de découverte, la page d'autorisation, les scopes réels du Token et tools/list font foi. Les affirmations d'anciens documents selon lesquelles « l'ontologie n'a jamais de SQL par défaut » ou « il n'y a que six outils » ne peuvent servir de base à l'implémentation actuelle.
Isolation des états
Sessions, rapports, candidats et plans d'action ont chacun leurs propriétaires et leurs périmètres. Le rafraîchissement de l'access token ne transfère pas le travail du Grant d'origine à un autre Grant. Ne fusionnez pas dans la connexion actuelle les sessionId, reportId, planId, jetons d'approbation ou Tokens de source renvoyés par une autre connexion.
Messages HTTP et MCP modernes
Envoyez correctement les métadonnées par requête et les en-têtes de routage correspondants, et traitez séparément HTTP et les résultats d'outils.
| Élément | Comportement r56 |
|---|---|
| Transport | Streamable HTTP sans état, POST JSON-RPC |
| Identifiants de version pris en charge | 2026-07-28 ainsi que 2025-11-25 2025-06-18 2025-03-26 |
| Méthodes modernes | server/discover, tools/list, tools/call, resources/list, resources/read, ouvertes selon les capacités réelles |
| En-tête de session | Aucun Mcp-Session-Id n'est attribué |
| GET et DELETE | /mcp et /mcp/business renvoient 405 |
| Notifications SSE du serveur | Non fournies par ces deux points d'entrée MCP publics |
| Cache du catalogue | La découverte moderne et les listes renvoient ttlMs=60000 et cacheScope=private. |
| Résultat ordinaire | Le résultat moderne contient resultType=complete et les métadonnées d'identité de service |
Contenu devant correspondre
- MCP-Protocol-Version est cohérent avec io.modelcontextprotocol/protocolVersion dans params._meta.
- Mcp-Method est cohérent avec la méthode JSON-RPC.
- Pour tools/call, Mcp-Name correspond à params.name ; pour resources/read, l'en-tête de nom correspond à l'URI.
- Chaque requête moderne transporte un objet io.modelcontextprotocol/clientCapabilities ; le clientInfo standard doit également être fourni pour faciliter l'identification du client.
Exemple d'appel
{
"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": {}
}
}
}Pour HTTP, les en-têtes correspondants sont Mcp-Method: tools/call et Mcp-Name: dfc_ontologies. Tous les ACCESS_TOKEN des exemples sont des espaces réservés. Ne placez pas le Bearer Token dans l'URL, les paramètres JSON ou les clés de cache.
Lecture des résultats
Traitez d'abord le statut HTTP, puis vérifiez l'erreur JSON-RPC ; en présence d'un result, vérifiez ensuite isError. Un résultat d'outil réussi fournit généralement structuredContent, accompagné d'un contenu textuel contenant le même JSON métier ; privilégiez le canal structuré et évitez d'agréger text et structuredContent comme s'il s'agissait de deux faits indépendants. Un HTTP 200 peut véhiculer un échec d'outil.
Ressources publiques et UI
Les ressources de documentation intégrées ne dépendent pas de MCP Apps. Le point d'entrée de l'espace de travail métier n'obtient pas pour autant les ressources de documentation de l'ontologie. Les clients prenant en charge la visualisation doivent découvrir l'UI correspondante via les capacités réelles et les _meta des outils, sans deviner les URI de ressources non renvoyées.
Compatibilité des clients à l'ancien protocole
Conservez une génération de protocole cohérente avec les clients qui utilisent encore la poignée de main d'initialisation.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Envoyez initialize et lisez la version de protocole et les capabilities négociées par le serveur.
- Envoyez la notification d'initialisation terminée requise par le protocole du client ; les notifications n'ont pas de résultat d'outil ordinaire.
- Utilisez tools/list pour lire les outils actuellement autorisés, puis envoyez tools/call.
- Gardez les en-têtes et les messages cohérents avec la génération de protocole de la requête en cours ; n'appliquez pas l'ancien flux initialize ou ping à un message 2026-07-28.
L'ancien protocole utilise le même Bearer/OAuth, les mêmes permissions et le même contrat d'outils. Cela ne signifie pas que le serveur fournit nécessairement une connexion SSE persistante de type hérité ou Mcp-Session-Id ; les services publics de r56 restent sans état.
Erreurs de protocole
| Situation | Résultat typique | Traitement |
|---|---|---|
| Incohérence entre les en-têtes modernes et le message | HTTP 400 JSON-RPC -32020 | Corrigez les en-têtes, les métadonnées et les noms d'outils |
| Version non prise en charge | -32022 avec la liste des versions prises en charge | Choisissez un protocole réellement pris en charge |
| Méthode inconnue | JSON-RPC -32601, les requêtes modernes peuvent renvoyer HTTP 404 | Vérifiez la génération de protocole et la méthode |
| Paramètres manquants ou invalides | JSON-RPC : erreur de paramètres, ou isError de l'outil | Corrigez selon l'inputSchema réel |
Choisir les bons outils et canaux de preuve
Routez selon le problème métier non résolu, sans refaire les mêmes preuves via une chaîne d'appels figée.
| Tâche | Outil privilégié | Preuves nécessaires à l'achèvement |
|---|---|---|
| Découvrir les thèmes et ressources autorisés | dfc_ontologies dfc_ontology_resources | Types réels des identifiants de ressources et périmètre de visibilité actuel |
| Statistiques de tables et TopN | dfc_table query | Reçu d'exécution réussie et evidenceRows complets |
| Consulter une réglementation, un contrat ou un rapport | dfc_ontology_query ou knowledge search/detail | Texte intégral, autorisé et exploitable comme fait |
| Localiser un objet du graphe | dfc_ontology_graph search/neighbors | Localiser la source réelle, puis obtenir le fait correspondant |
| Interaction par mots-clés d'origine | dfc_manual puis dfc_search | Résultats réels dans le modèle d'origine et les cadres métier |
| Analyse fusionnée et rapports | dfc_analysis_* ou dfc_report_* | État réel de chaque branche structurée et des preuves documentaires |
| Modifier la présentation ou le modèle d'ontologie | dfc_authoring_* et les outils artifact | Vérifier séparément les candidats, plans, approbations et applications réelles |
| Exécuter une commande métier | dfb_* de /mcp/business | Contrats publiés et reçu de l'ActionPlan d'origine |
Éviter les appels inutiles
Lorsque la structure de table actuelle, complète et autorisée est déjà disponible, n'exigez pas un nouveau detail à chaque requête ; lorsque la localisation et les preuves fiables existent, ne répétez pas la même recherche. S'il manque une dimension, effectuez une requête complémentaire bornée. Lorsqu'un échec est explicitement non réessayable, comblez d'abord la lacune au lieu de substituer « réessayer » à l'analyse.
Exclusions de Flash
dfc_etl capabilities peut renvoyer available=false et ETL_NOT_INCLUDED_IN_OT_FLASH. La documentation statique des fonctions ETL intégrées sert de référence inter-produits ; elle ne prouve pas qu'ETL est installé dans Flash et n'autorise pas l'Agent à basculer automatiquement vers Heavy ou un autre tenant pour l'exécution.
Ressources d'ontologie et types d'identifiants
Obtenez d'abord les coordonnées réelles des ressources afin d'éviter de confondre noms de stockage, identifiants de documents et identifiants de base de connaissances.
- Appelez dfc_ontologies et parcourez avec page et pageSize les ontologies accordées par cette autorisation et toujours lisibles.
- Appelez dfc_ontology_resources avec un vrai ontologyId ; choisissez selon le besoin tables, answers, pinboards, documents et knowledgeBindings.
- Traitez la pagination séparément pour chaque type de ressource. pageSize est limité à 100 ; ne déduisez pas l'étendue complète d'une ressource de la première page.
- Conservez les types déclarés et les identifiants d'origine des ressources et réutilisez-les tels quels dans les appels suivants.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordonnée | Source | Ne peut pas remplacer |
|---|---|---|
| ontologyId | Liste des ontologies autorisées ou contexte actuel valide | L'identifiant d'une autre ontologie |
| Identifiant de ressource de table | Liste tables ou contexte fiable | physicalName ou nom de table affiché |
| tblDisplayName colDisplayName | Métadonnées actuelles des tables et colonnes | Identifiant SQL physique deviné |
| knowledgeId | knowledgeBindings ou reçu réel de recherche de connaissances | Identifiant de ressource de document |
| assetId documentId chunkId evidenceId | Le même reçu réel de localisation | Champs assemblés à partir de résultats de localisation différents |
| rid revisionId releaseId | Modèle publié ou contexte candidat côté serveur | Identifiant généré par le client ou latest |
Conventions de précision
Tous les identifiants de ressources 64 bits doivent être traités de préférence comme des chaînes décimales, sans passer par Number en JavaScript. Certains schémas métier acceptent string ou integer, ce qui ne signifie pas qu'on puisse sacrifier la précision des entiers. Les locateurs opaques, UUID, les hachages et les jetons à usage unique doivent également être conservés tels quels.
Contrat de requête et de structure pour les tables Doris
Exécutez des requêtes SQL en lecture seule sur des tables autorisées, en préservant la sémantique de sortie, les valeurs exactes et l'intégrité.
Lire la structure
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}detail utilise l'identifiant réel de la ressource de table. Vérifiez schemaComplete, tblDisplayName, colDisplayName dans columns et le sqlDataType faisant autorité, ainsi que le queryContract renvoyé. dataType n'est qu'un mappage de compatibilité ; le nom de stockage physique n'est pas le nom de table à soumettre à SQL.
Exécuter la requête
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}Contraintes SQL
- Utilisez les noms de tables et de colonnes affichés, avec des identifiants entre guillemets doubles. La requête doit être une seule requête Doris en lecture seule dans le périmètre de l'ontologie.
- Listez explicitement les sorties ; SELECT * et table.* sont interdits ; ils ne permettent pas de contourner les permissions de colonnes enregistrées via les colonnes physiques.
- Les jointures utilisent un JOIN ... ON explicite ; NATURAL JOIN et JOIN USING sont refusés.
- Sont autorisées les expressions en lecture seule légitimes : agrégations multidimensionnelles, CTE, fenêtrage, CASE, COUNT(DISTINCT ...), etc. ; le fait que la validation sémantique ne couvre pas une expression n'équivaut pas à une interdiction générale de l'exécuter.
- Effectuez d'abord les agrégations, tris et classements dans SQL, puis appliquez la limite de résultats. maxRows vaut 100 par défaut, 200 au maximum.
Dates et fuseaux horaires
| Type ou cible | Forme | Remarque |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) et CURRENT_DATE | On ne peut pas présumer le type date à partir d'un littéral textuel |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) et CURRENT_TIMESTAMP | Vérifiez le fuseau de la source et le fuseau de la session |
| Temps relatif | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Utilisez la fonction courante correspondante pour les dates et les horodatages |
| Regroupement temporel | YEAR(colonne) ou DATE_TRUNC(colonne, 'month') | Utilisez un alias unique pour chaque sortie ; queryContract fait foi |
Le DATE('now', ...) de SQLite ne relève pas du contrat de dates Doris de ce point d'entrée. Ne transposez pas dans le SQL en production la méthode de vérification hors ligne SQLite des exemples de la documentation.
Lire le reçu de requête v8
evidenceRows est le seul canal de l'Agent pour les données de lignes ; les raw data ne sont pas exposées à l'Agent. Les nombres SQL sont encodés en chaînes décimales exactes JSON ; déterminez leur valeur numérique et leur type métier via resultColumnContracts, sans les interpréter comme VARCHAR au motif que la valeur JSON est une chaîne. Lisez executionReceipt ainsi que les informations de complétude et de troncature, et conservez les informations de source telles que evidenceRowsSha256.
Les sorties de requête accompagnées d'un reçu d'exécution citable peuvent être citées telles quelles ; seules les sémantiques validées côté serveur autorisent des recalculs déterministes ultérieurs. Ne devinez pas « solde cumulé », « valeur de fin de période » ou « 币种 » d'après les noms de champs et ne complétez pas les unités vous-même. Les résultats à zéro ligne, les échecs ou les troncatures ne doivent pas être décrits comme des statistiques complètes.
Top3 multidimensionnel et gestion de la troncature
Établissez les classements par agrégation et fonctions de fenêtrage côté serveur ; n'effectuez pas de calculs secondaires sur des résultats incomplets.
Le fichier fourni examples/top3.sql utilise la table d'exemple : il agrège d'abord par 区域, 类别 et 产品, puis exécute ROW_NUMBER dans chaque 区域 et 类别, en utilisant le nom de 产品 comme ordre stable en cas d'égalité des montants. Demander maxRows=100 suffit pour les 36 lignes de l'exemple ; d'autres données métier doivent être évaluées selon le nombre réel de groupes.
- Obtenez la structure réelle et la définition métier actuelle, et précisez 币种, la période, 订单状态 et les règles d'égalité.
- Soumettez une requête SQL qui effectue l'agrégation et le classement côté serveur. N'interrogez pas d'abord le seul total par 区域 pour le traiter ensuite comme un classement des 产品 par 类别.
- Vérifiez le contrat de colonnes de sortie et les evidenceRows réels, et confirmez que le retour couvre tous les groupes requis.
- En cas de troncature, effectuez des requêtes par partitions bornées selon les limites prises en charge par le serveur, par exemple en obtenant séparément le Top3 complet de chaque 区域 ; conservez à chaque fois la même définition métier.
- Si la période source change, relancez la requête et précisez la nouvelle version ; ne mélangez pas des versions de données différentes ni des curseurs obsolètes.
Reprise sur erreur
TABLE_SCHEMA_INCOMPLETE impose de corriger la structure ou d'obtenir la structure complète ; les échecs tels que ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID sont traités selon le errorCode, retryable et remediation renvoyés. N'affirmez pas que « toutes les requêtes multidimensionnelles GROUP BY ou fonctions de fenêtrage sont interdites » et n'inventez pas de classements sans résultats de requête.
Recherche de connaissances : texte intégral et éligibilité des preuves
Séparez le repérage, la lecture et la citation de faits, et conservez la source et la complétude.
Deux parcours courants
| Parcours | Finalité | Points clés |
|---|---|---|
| dfc_ontology_query | Rechercher dans les connaissances liées à l'ontologie, avec routage possible par le graphe | Vérifier le canonical answerContextItems complet et l'éligibilité des preuves |
| dfc_knowledge_search → chunk dfc_knowledge_detail | Localiser par recherche explicite, puis lire le fragment sélectionné | Les aperçus de recherche ne constituent pas des faits ; lire le texte intégral correspondant au même repérage |
{"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>"
}}Conditions pour une utilisation comme fait
- Vérifiez l'ACL actuelle, la complétude du contenu ainsi que canonicalFactEligible, citationEligible ou le contrat d'exécution correspondant côté serveur.
- Le contenu complet est lié à contentSha256. Traitez les troncatures, les omissions dues au budget ou les contenus de faible qualité selon les champs réels.
- Les métadonnées du document, page_context, la position dans le graphe, les résumés de recherche et les aperçus ne remplacent pas le texte canonique original.
- Copiez en priorité evidenceId ; lorsque chunkId et documentId sont requis, ils doivent provenir du même résultat de repérage, sans concaténation ni invention.
Routage par le graphe
Les résultats de search/neighbors sont des informations de repérage. Ne transmettez à l'opération query de l'ontologie que l'objet routeLocator complet renvoyé par le serveur, y compris les champs de liaison, de version et de preuve. N'encapsulez pas vous-même un assetId ou un knowledgeId dans un locator prétendument émis par le serveur, et ne renvoyez pas de preuve de source affirmée par le modèle.
Reconstitution de documents structurés
Le structuredPlan de dfc_ontology_query est une reconstitution restreinte avec validation déterministe, spécialement conçue pour les tableaux de documents irréguliers. N'utilisez le plan déclaré par le serveur qu'une fois renvoyées les valeurs actuelles de executionContractSha256, tableIndex, ainsi que les colonnes et le tableau complet. Les tables métier ordinaires déjà importées doivent passer par dfc_table SQL ; ne considérez pas la reconstitution de tableaux Markdown comme un moyen de contourner l'autorisation de requête de table.
Stratégie de recherche
knowledgeIds est généralement omis afin de couvrir les liaisons actuellement activées ; s'il est transmis, n'utilisez que les véritables ID de base de connaissances issus de knowledgeBindings. Ne considérez pas un ID de ressource de document comme un ID de base de connaissances. Effectuez de nouvelles recherches bornées pour les questions non résolues, en évitant de répéter à l'identique une recherche qui n'apporte aucune nouvelle preuve.
Modèle Search natif et sessions
Via dfc_search, utilisez le protocole par mots-clés de Rust Search et attendez l'état final des trames métier d'origine.
Lire la documentation avant de découvrir les capacités
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search nécessite un search:operate explicite. Il encapsule le WebSocket de mots-clés d'origine et ne réécrit pas les mots-clés en requêtes SQL ou LLM. La session est liée au locataire, à l'utilisateur, au Grant, au client et au modèle actuels, et les permissions d'origine sur les tables et colonnes sont revérifiées à chaque opération.
Flux de session minimal
{"name":"dfc_search","arguments":{
"action":"model_create","data":{"tableIds":["<ACTUAL_TABLE_ID>"]}
}}
{"name":"dfc_search","arguments":{
"action":"open","data":{"sourceToken":"<MODEL_SOURCE_TOKEN>","language":"en-US"}
}}
{"name":"dfc_search","arguments":{
"action":"poll","data":{"sessionId":"<SEARCH_SESSION_ID>","waitMillis":10000}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"assist","datas":{}}}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"search","datas":{"search":"<QUERY_USING_ACTUAL_COLUMNS>","ambiguities":[]}}}
}}- model_create utilise de 1 à 100 ID réels de tables autorisées, ou model_read lit un sourceToken que vous possédez déjà.
- open ne renvoie que initializationSent ; interrogez d'abord (poll), lisez la réponse métier init d'origine et confirmez le succès.
- Lisez l'assist et les suggestions, puis envoyez un message natif pris en charge. Dans query datas, isNl est fixé à false par le wrapper.
- Lisez les trames en continu en distinguant les suggestions, l'analyse, la réception et le résultat métier final.
- Terminez par close ; pour annuler, utilisez cancel et vérifiez l'état réel de la tâche pour confirmer l'arrêt.
| action | data | Signification |
|---|---|---|
| capabilities | Omis ou objet vide | Lire les actions, les commandes, le TTL et les notes de transport |
| model_create | Tableau tableIds | Créer un modèle autorisé pour l'utilisateur courant |
| model_read | sourceToken | Lire le modèle en filtrant les colonnes non autorisées et les configurations de sources sensibles |
| open | sourceToken et language facultatif | Établir une session native et envoyer init |
| request | sessionId et message | Envoyer un message du protocole natif type/datas |
| poll | sessionId et waitMillis entre 0 et 30000 | Récupérer les trames actuellement en mémoire tampon, avec une attente bornée possible |
| cancel close | sessionId | Fermer cette session native ; ne permet pas d'affirmer un état final BI |
Commandes natives prises en charge
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteLa casse des commandes et la structure datas suivent les capabilities actuelles et le protocole de session d'origine. N'ajoutez pas d'actions inexistantes à request ; par exemple, l'orthographe de disambiguite doit être conservée telle quelle conformément au protocole réel. La taille maximale d'un message est de 256 Ki caractères.
Sessions et complétude
Le TTL de session est de 10 minutes et la session n'est conservée que pendant la durée de vie du processus courant ; il ne s'agit pas d'une tâche durablement récupérable. La mémoire tampon contient au maximum 256 trames et est soumise à une limite de mémoire ; si bufferOverflow=true, les trames récupérées ne doivent pas être considérées comme un résultat complet. En cas d'erreur de transport, interrogez d'abord (poll) la session d'origine ; ne renvoyez pas aveuglément une requête potentiellement déjà exécutée.
Le wrapper actuel ne fournit pas l'enregistrement des réponses ou des pinboards, la lecture/écriture de l'historique ni la restauration de contexte arbitraire. L'existence de exportContext ne signifie pas que tout contexte peut être restauré de façon autonome. Pour enregistrer des résultats, utilisez les capacités de ressources d'origine réellement exposées par l'instance ; n'inventez pas d'action.
Conventions de langue et de région
Respectez les limites entre la locale de l'interface, les dictionnaires de requête, la langue de retour et les noms de champs d'origine.
La priorité est : langue explicitement demandée, langue du système applicatif, locale du nœud d'exécution réel. Une valeur omise, null, une chaîne vide ou des espaces ne provoquent pas de repli systématique sur le chinois. Les valeurs de région du languageRegistry doivent rester exactes ; ne fusionnez pas arbitrairement en-GB, fr-CA, pt-BR, es-US ou ar-AE en une autre région.
| Langue ou région | Locale de requête | Description |
|---|---|---|
| Chinois simplifié, chinois traditionnel | zh-CN zh-Hant | Les règles chinoises d'origine diffèrent du catalogue en chinois traditionnel |
| Anglais des États-Unis, du Royaume-Uni, d'Australie et du Canada | en-US en-GB en-AU en-CA | Les packages UI/mots-clés peuvent être partagés ; les métadonnées régionales sont conservées |
| Allemand, italien, russe | de-DE it-IT ru-RU | Utiliser selon les suggestions de la session courante |
| Espagnol d'Espagne et d'Amérique latine | es-ES es-US | L'ID de région du produit est es-US. |
| Français de France et du Canada | fr-FR fr-CA | Les ID de région ne sont pas fusionnés |
| Portugais du Portugal et du Brésil | pt-PT pt-BR | Le catalogue et les conventions régionales sont conservés séparément |
| Néerlandais, danois, norvégien, finnois, suédois | nl-NL da-DK nb-NO fi-FI sv-SE | Le norvégien est en Bokmål |
| Japonais, coréen | ja-JP ko-KR | Ne segmentez pas selon les règles d'espacement de l'anglais |
| Arabe d'Arabie saoudite et des Émirats arabes unis | ar-SA ar-AE | Les textes d'interface prennent en charge le RTL ; les identifiants du protocole ne sont pas inversés |
Utiliser le catalogue de mots-clés
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}Le catalogue statique de mots-clés de dfc_manual ne comprend que les locales explicitement listées ; si la locale est omise, la référence anglaise est utilisée ; il s'agit d'une valeur par défaut de référence, pas d'une règle d'analyse de la langue de requête. Lorsqu'aucun catalogue statique n'est fourni pour une variante régionale, obtenez les suggestions réelles via l'assist de la session courante ; ne fabriquez pas d'alias ni de résultats de repli. names accepte au maximum 32 éléments par appel.
Contenu à ne pas traduire
- Tables, colonnes, valeurs d'énumération, noms de clients, noms de formules et autres chaînes réelles du modèle.
- Noms d'outils, action, scope, champs de schéma, codes d'erreur et valeurs d'état.
- ID de ressources, hachages, locators opaques et références émises par le serveur.
Par exemple, une question en allemand peut interroger la colonne affichée en chinois « 销售金额 ». La remplacer par un nom de colonne allemand produirait un autre identifiant, et non une traduction d'interface. Après changement de langue, réinitialisez la session ou mettez-la à jour selon le protocole d'origine, puis récupérez à nouveau les suggestions et les candidats d'ambiguïté.
Analyse fusionnée et résultats interactifs
Dans les outils d'analyse à ouverture conditionnelle, conservez l'autorisation, la version, les branches et l'état des preuves.
dfc_analysis_* est contrôlé par datafocus.mcp.analysis.tools.enabled. La partie structurée continue de passer par la requête Search faisant autorité et par la politique de lignes actuelle ; la partie documentaire récupère à nouveau le texte intégral sous l'ACL actuelle. Ces outils ne constituent pas un point d'entrée pour du SQL ouvert, des instructions arbitraires ou l'injection de filtres arbitraires.
| Outil | Finalité | Coordonnées requises |
|---|---|---|
| dfc_analysis_ask | Poser une question d'analyse en langage naturel | ontologyId, question ; language et sessionId facultatifs |
| dfc_analysis_result_get | Lire un résultat déjà renvoyé | ontologyId sessionId resultId |
| dfc_analysis_refine | Poursuivre ou modifier à partir du dernier résultat complet | expectedRevision du résultat d'origine et clé d'idempotence stable |
| dfc_analysis_page | Obtenir une page d'une branche côté serveur | Branche et version de résultat d'origine, pageNo pageSize |
| dfc_analysis_cancel | Annuler un résultat encore en cours | Session et résultat d'origine |
| dfc_analysis_close | Libérer une session qui n'est plus en cours de travail | Session d'origine |
Lancer l'analyse
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Lisez le sessionId, resultId, l'état et la revision renvoyés ; poursuivez si nécessaire la lecture du résultat d'origine.
- Vérifiez pour chaque branche structurée l'état, la complétude, la politique de lignes et la source ; l'achèvement d'une branche ne signifie pas que l'ensemble de l'analyse est complet.
- Vérifiez les preuves documentaires, le registre des faits, l'éligibilité des citations et les limites. Les récits générés par le modèle ne peuvent pas à eux seuls élever l'éligibilité des preuves.
- Pour une question de suivi, basez-vous sur le dernier résultat complet en transmettant expectedRevision ; toute nouvelle tentative d'une même modification réutilise la même clé d'idempotence.
- Avant de fermer, confirmez que la session ne travaille plus ; l'annulation et la fermeture sont des actions distinctes.
Filtrage contrôlé et pagination
filter_patch utilise les branchId, fieldRef, valueRef fournis par le serveur et les opérateurs autorisés ; le filtrage typé actuel ne déclare que EQ. Il est interdit de remplacer les références opaques par du SQL brut, des tableId, columnId ou par un arbre de filtrage fabriqué côté client. La pagination pageNo commence à 1, avec un maximum de 10000 ; pageSize est limité à 100.
Indications de capacités et comportement
Les annotations des outils sont des indications destinées au client, et non des autorisations de sécurité. Certains modèles génériques utilisent readOnlyHint, ce qui ne remplace en rien le jugement sur l'action réelle ; l'annulation, la fermeture et la création de rapports modifient l'état de travail correspondant. Agissez toujours selon la sémantique de l'outil, les objectifs de l'utilisateur et les permissions côté serveur.
Rapports visuels persistants et Apps MCP
Créez des rapports récupérables, puis lisez leurs résultats et leurs interfaces interactives selon les permissions actuelles.
dfc_report_* est contrôlé par datafocus.mcp.analysis.report-tools.enabled et exige les scopes metadata et table query. Il se distingue des sessions Search internes au processus : les rapports utilisent un reportId persistant ; la persistance ne signifie pas que les permissions cessent d'être vérifiées.
{"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>"
}}Flux de travail
- À la création, utilisez un idempotencyKey stable, de 8 à 128 caractères pris en charge.
- Enregistrez reportId, interrogez status et vérifiez l'état réel : terminé, échoué, partiellement terminé ou annulé.
- À la lecture des résultats, vérifiez les branches structurées, les visualisations, les sources des faits, les références documentaires et l'exhaustivité.
- Pour annuler un rapport inachevé, utilisez le reportId d'origine ; ne créez pas un autre rapport à la place de l'annulation.
- Après un délai d'attente réseau, lisez d'abord l'état du rapport d'origine ; le rejeu avec la clé d'idempotence d'origine doit préserver la même intention métier.
MCP Apps
Les clients prenant en charge les extensions UI découvrent les pages de rapport via tools/_meta et la découverte réelle des ressources. La page de rapport persistante correspondant à r56 est ui://datafocus/analysis-report/v16/index.html ; l'analyse interactive utilise les références de ressources serveur appropriées ; le client ne doit pas coder ces valeurs en dur au lieu d'utiliser celles renvoyées par l'outil. Sans extension UI, les résultats structurés restent lisibles.
Liaison de source
La lecture des rapports revérifie le Grant, l'ontologie, la liaison à l'Origin de la requête et les permissions actuelles sur les tables. Les intégrations inter-origines du navigateur doivent utiliser des origines réelles approuvées ; le client ne contourne pas la liaison par un en-tête Origin falsifié. Un ancien reportId n'est ni un lien public permanent, ni un justificatif d'accès entre utilisateurs.
Artefacts : brouillon, aperçu, plan et application
Confiez le contenu généré au serveur d'origine pour normalisation, validation et approbation, sans laisser le modèle modifier directement les ressources de production.
Les outils d'artefacts exigent l'activation de la fonction authoring, un type d'artefact réel, les scopes correspondants et les droits d'écriture administrateur d'origine. Les types par défaut sont configurés sur CONTROL_PANEL_SPEC et VIEW_SPEC ; les autres types (formulaire, source HTTP ou script) sont en outre soumis à une configuration distincte. Flash ne comprend pas AutoML ; les types associés ne sont donc pas répertoriés comme artefacts disponibles dans cette version.
- dfc_authoring_capabilities lit les contrats et les actions disponibles pour le Grant actuel.
- dfc_artifact_context obtient un contexte délimité, contractVersion, contextHash, baseArtifactHash et baseArtifactVersion.
- Générez le candidat côté client selon le contrat réel, sans exécuter le code qu'il contient.
- dfc_artifact_submit soumet le contexte d'origine et le candidat, en conservant l'instruction identique et en utilisant un clientRequestId stable.
- Lisez proposalId, candidateHash, les résultats de validation et l'aperçu ; en cas d'erreur réelle, révisez le candidat sans simuler un statut de réussite côté serveur.
- Pour un nouvel aperçu, utilisez dfc_artifact_preview et le même hachage de candidat.
- dfc_artifact_plan crée un plan immuable à partir du candidat réel, de la version cible et de la clé d'idempotence.
- Traitez l'approbation selon l'interaction d'origine ou une politique déjà autorisée, puis appelez dfc_artifact_apply ; seul le reçu APPLIED atteste d'une application réelle.
Requête de contexte minimale
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC utilise le projectId actuellement autorisé ; lors de la modification d'un artefact existant, utilisez le artifactId réel. Les champs tels que variables, previewInput et viewport sont fournis selon le contrat renvoyé, sans deviner la structure interne des candidats.
Concurrence et nouvelles tentatives
Le plan est lié à la version cible, au hachage du candidat et à la clé d'idempotence. Après un changement de cible, l'ancien plan ne peut plus être appliqué ; relisez le contexte et traitez les conflits réels. Un délai d'attente du transport ne prouve pas un échec : interrogez d'abord avec dfc_artifact_status le proposalId ou le planId d'origine. READY n'est pas APPLIED.
Approbation et politiques automatiques
Les plans d'artefacts génériques exigent l'approbation humaine d'origine. Les plans conformes à la politique de publication automatique de l'ontologie sont traités selon approvalMode, sans exiger de l'utilisateur qu'il signe en plus une approbation inventée par l'Agent. approvalToken est un élément émis par le serveur ; l'Agent ne peut pas le remplacer par une chaîne qu'il écrit lui-même ; l'inputSchema réel et le reçu du plan déterminent les champs obligatoires.
Contrat de création et de publication des candidats d'ontologie
Utilisez des déclarations d'ontologie et des configurations de publication à versions distinctes ; n'appliquez pas le contrat des artefacts de simple présentation à la publication de modèles.
Créer un candidat
Le conteneur d'ontologie doit déjà exister et figurer dans le Grant. Utilisez dfc_ontology_table_schema pour vérifier les champs de source structurée actuels et l'empreinte Binding v4 ; les champs peuvent se limiter à sourceField pour une découverte automatique du type. Une déclaration explicite DECIMAL exige la précision et le nombre de décimales actuels ; les autres types ne portent pas ces deux champs.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Candidats et configuration de publication
| Contrat | Finalité | Limites essentielles |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Créer un candidat à partir de déclarations locales | Sources réellement autorisées, compilation côté serveur ; aucune preuve d'achèvement n'est acceptée |
| ontology-workspace-create-mcp-submit-v2 | Mélanger des déclarations locales et des références publiées exactes | Fournir les releaseSelections exacts et les dépendances de fermeture |
| ontology-publication-mcp-submit-v1 à v3 | Lier un candidat existant à une demande de plan de publication | Coordonnées explicites ; cible, source, approbation et validation restaurées par le serveur |
| ontology-publication-mcp-submit-v4 à v6 | Configuration associée à la publication automatique, activée séparément | À utiliser uniquement si capabilities et le schéma réel le déclarent |
| ontology-initial-activation-retirement-submit-v1 | Opération contrôlée d'activation initiale et de retrait | Plan distinct, nouvelle approbation humaine et périmètre exact |
Ordre de publication
- Obtenir les workspaceId, workspaceRevision, candidateHash du candidat actuel ainsi que la source réelle.
- Choisir la version du contrat selon les capacités du serveur ; soumettre les coordonnées telles que releases et selection, sans joindre de champs s'affirmant comme « approuvé » ou « validé ».
- Conserver le proposalId renvoyé par submit et le idempotencyKey d'origine. submit et MODEL_PLAN sont deux phases d'une même requête.
- Appeler dfc_artifact_plan avec le candidat d'origine, la version cible et la même clé d'idempotence.
- PLANNING_INCOMPLETE signifie seulement qu'aucun plan valide n'a encore été formé ; VALIDATION_UNSATISFIED indique que la validation actuelle présente encore des lacunes, à traiter selon nextAction.
- Après le succès du plan, poursuivre selon HUMAN_REQUIRED ou POLICY_AUTO, avec l'approbation et les capacités de publication d'origine.
- Confirmer le résultat avec le reçu APPLIED puis par une lecture réelle du modèle publié et une requête autorisée.
Délais d'attente et reprise
Après un délai d'attente de PLAN, lire le proposalId d'origine. MODEL_PLAN_SUBMITTED est une requête inachevée ; MODEL_PLAN_COMPLETED signifie qu'il faut restaurer le reçu d'origine avec les coordonnées et la clé d'origine, et non créer une nouvelle requête côté client. Une lacune de validation à l'état final ne se transforme pas en publication validée par un changement de clé ou des soumissions répétées.
Permissions métier humaines
Les instructions et déclarations fournies par l'Agent constituent des entrées d'Agent, et non une signature de politique humaine. MODEL_AUTHOR, MODEL_PUBLISH, la délégation de publication automatique, la confirmation métier, la confiance en clé publique, le budget et les ACL de source restent déterminés par les mécanismes d'origine. Aucun champ côté client ne peut remplacer ces faits.
Modèle publié, requêtes sur les candidats et fermeture des références
Utilisez les connaissances métier publiées selon des versions exactes et préservez le caractère provisoire des candidats non publiés.
published_model, published_query et candidate_query de dfc_ontology_graph sont des configurations structurées à ouverture conditionnelle, et non de simples synonymes de search/neighbors. Leur autorisation repose sur table query et sur les permissions de lecture de modélisation nécessaires ; la visibilité dans le graphe ne remplace pas les permissions sur les tables.
Lire un modèle publié
- Lorsque l'énumération action de l'outil contient réellement published_model, soumettre un releaseId réel à l'état committed.
- v1 renvoie des modèles de requêtes autorisées ; v2 ajoute les références PERSISTED exactes et releaseSelections ; v3 ajoute les références de dépendances, les domainRef exacts et des modèles de liaison compacts.
- Choisir objets, propriétés, Binding, scope et versions à partir des valeurs réellement renvoyées, sans générer de RIDs ni utiliser latest.
- Soumettre la requête typée à structure fixe de published_query ; les résultats restent soumis aux autorisations actuelles de source et de champ.
Requête sur les candidats
candidate_query utilise le workspaceId réel, revision, candidateHash et les déclarations de candidat. En cas de mélange avec des références publiées, utiliser les coordonnées typées v2 correspondantes LOCAL/PERSISTED et des sélections exactes. Les résultats des candidats restent toujours non publiés et provisoires ; ils ne constituent pas une connaissance confirmée par l'entreprise.
Maintenance partielle et fermeture
Ne sélectionner que les dépendances transitives nécessaires à la racine du candidat, et garantir que chaque référence publiée possède un releaseSelections exact. Copier le contenu publié, ne soumettre qu'une liste d'identifiants ou étendre la sélection à toutes les ressources historiques ne peut remplacer la vérification actuelle des dépendances et des sources.
Le paramètre query de ces actions est un objet typé versionné ; il n'accepte ni SQL, ni identifiants de tables physiques, ni noms de tables sources en remplacement de leurs références métier. Les modèles de métadonnées et les résultats du graphe n'ont pas, en eux-mêmes, qualité de référence factuelle.
Délégation de tâches à l'agent d'ontologie
Reprenez le travail à l'aide de tâches persistantes et du Grant d'origine, sans considérer les instructions de l'Agent comme une approbation humaine.
dfc_ontology_agent n'apparaît que si le Pi Runtime réel et les permissions associées sont disponibles. QUERY utilise des capacités de lecture ; AUTHORING exige en outre un rôle de modélisation et le scope authoring correspondant. Il n'ouvre pas un autre moteur d'exécution sans contraintes.
{"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>"
}}Jeu de paramètres strict
start utilise contractVersion, action, ontologyId, mode, instruction, idempotencyKey ; status/cancel utilisent contractVersion, action, ontologyId, runId. Le serveur vérifie l'ensemble exact de champs selon l'action. instruction est limitée à 16000 caractères ; la clé compte de 1 à 128 caractères pris en charge et commence par une lettre ou un chiffre.
Reprise et annulation
- Conserver le runId, le Grant, le mode et la clé d'idempotence d'origine.
- La même clé et la même instruction reprennent le même run, sans soumettre une autre tâche ; changer d'instruction avec la même clé est refusé.
- status interroge l'état de la tâche d'origine. Après achèvement, vérifier malgré tout ses requêtes de table, ses preuves ou ses reçus de publication.
- L'annulation utilise le runId d'origine ; confirmer le résultat selon l'état réel de la tâche.
L'achèvement d'un run n'est pas un reçu de publication de modèle. Une tâche de publication doit toujours être confirmée par l'état de l'artefact d'origine et les vérifications de source ; QUERY n'emporte aucun droit implicite d'écriture ou de publication.
Espace de travail métier MCP
Interrogez les enregistrements à partir des contrats métier publiés et exécutez les commandes via l'ActionPlan d'origine.
/mcp/business utilise une ressource protégée distincte et la sélection d'un système métier ; il ne peut pas réutiliser un Grant d'ontologie à la place d'une autorisation métier. Le système métier doit être publié, appelable par l'Agent, conforme à la politique de sécurité d'origine, et l'utilisateur actuel doit disposer réellement des rôles et capacités d'exécution requis.
| Scope | Outils | Limites |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Découvrir uniquement les systèmes autorisés et actuellement appelables |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Enregistrements lisibles par l'utilisateur actuel et ses propres plans |
| business-system:plan | dfb_action_plan | Créer uniquement des plans immuables, sans exécution |
| business-system:execute | dfb_action_execute | Autorisation explicite distincte, exécution selon le risque et l'approbation |
- dfb_systems découvre les systèmes autorisés.
- dfb_system_describe lit le contrat publié actuel, releaseId, ainsi que tous les hachages, requêtes et commandes.
- dfb_query utilise le queryKey publié, en spécifiant au besoin objectKey, state, page et pageSize. Il ne s'agit pas de SQL arbitraire.
- dfb_record et dfb_work_items lisent les enregistrements et les tâches en attente actuellement autorisés.
- Avant l'exécution, fournir avec dfb_action_plan le releaseId réel, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey et le payload du contrat.
- Vérifier riskClass, requiresApproval et status ; conserver expectedRecordVersion pour les enregistrements cibles concernés.
- dfb_action_execute n'exécute que les plans prêts et détenus par la connexion actuelle ; les jetons d'approbation requis pour une approbation humaine sont émis par DataFocus.
- Après un échec ou un délai d'attente, dfb_action_status restaure le plan d'origine ; les nouvelles tentatives conservent la sémantique idempotente d'origine.
Liaison entre connexions et versions
Le plan est lié à l'identifiant d'isolation stable du Grant actuel. Après le rafraîchissement de l'Access Token, les plans de la même connexion restent traitables ; une autre connexion OAuth ne peut pas s'en emparer. À l'exécution, sont revérifiés la version publiée, les hachages IR/manifest, la version des enregistrements cibles, l'expiration du plan, l'idempotence et l'approbation. L'allowlist OAuth ne permet pas de contourner la gouvernance métier.
Entrées de connaissances métier et questions à confirmer
Enregistrez les entrées métier lorsque le processeur de production correspondant est ouvert, et préservez la limite de confirmation humaine.
Les quatre outils suivants sont ajoutés par le contrôleur MCP public selon les processeurs installés et le scope actuel. Ils n'apparaissent pas en permanence dans le catalogue de base. L'existence d'un schéma déclaré ne signifie pas que les processeurs, le budget ou les permissions de l'instance sont complets : il faut d'abord vérifier tools/list.
| Outil | Finalité | Autorisations ou effets non produits |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Enregistrer les entrées métier d'origine pour un espace de travail existant | Ne génère pas de questions à confirmer, n'approuve pas, ne publie pas |
| dfc_ontology_knowledge_input_preview | Prévisualiser temporairement des brouillons de questions à partir des entrées d'origine | Ne persiste pas, ne confirme pas, ne produit aucun reçu de production |
| dfc_ontology_knowledge_question_submit | Enregistrer des questions rédigées et non confirmées | Ne fusionne pas automatiquement les réponses, ne confère ni droit de responsable ni droit de publication |
| dfc_ontology_business_scope_initialize | Initialiser explicitement un périmètre consommateur d'un système métier | Pas de publication, pas d'activation, pas d'attribution d'accès aux sources |
Saisie et aperçu
- Obtenez workspaceId, workspaceRevision, localRef et preparationDigest à partir du travail de préparation réel.
- propose enregistre les entrées métier en utilisant le contrat input d'origine et une idempotencyKey stable ; une même clé ne peut correspondre qu'à une seule entrée.
- preview utilise la clé d'idempotence de l'entrée d'origine et ontologyId ; il renvoie à chaque fois la révision côté serveur et une fenêtre de 60 secondes, il ne s'agit pas d'un reçu d'achèvement de production idempotent.
- Lorsqu'il faut stocker une question, question_submit utilise une nouvelle clé de commande, la originalInputKey d'origine, une questionRevision, une validFrom, une validUntil et une expectedRevision explicites ; à la création, expectedRevision est null.
Point d'entrée de confirmation humaine
La knowledgeConfirmationPage renvoyée par question_submit n'est qu'un positionnement relatif de la page de connexion d'origine, avec préremplissage d'une question. Elle ne comporte pas de Bearer, n'ouvre pas la page automatiquement et ne confirme pas la connaissance. QUESTION_STORED_UNCONFIRMED indique explicitement que la confirmation n'a pas eu lieu ; n'écrivez pas dans la réponse que « la connaissance est publiée ».
Initialisation du périmètre consommateur
business scope initialize exige à la fois le droit de publication d'ontologie et la qualité de créateur du système métier précis ou le droit d'administration SourceManager sur celui-ci. Il utilise les coordonnées réelles de domainRid, domainRevisionId et businessSystemId ; le client ne peut pas renseigner un consumerScope ou une preuve d'achèvement arbitraire. Les INITIALIZED et COMPLETED renvoyés indiquent toujours explicitement published=false et activationAuthorized=false.
Ces requêtes passent également par des validations strictes de JSON, de jeu de champs, d'octets et de profondeur. La limite des requêtes d'entrée est de 1 Mio ; certaines opérations spécifiques ont des limites plus basses. Les schémas complets d'entrée et de sortie sont livrés avec la référence des outils ; n'appliquez pas la logique de paramètres permissive d'un wrapper MCP générique à ces contrats stricts.
Réponses, erreurs et nouvelles tentatives sûres
Interprétez les erreurs couche par couche, en conservant les coordonnées de tâche et la sémantique d'idempotence.
| Couche | Éléments à vérifier | Principe de traitement |
|---|---|---|
| Réseau et HTTP | Connexion, TLS, 401, 403, 400, 404, 405, etc. | Ne pas traiter une réponse en échec comme un résultat de requête ordinaire |
| JSON-RPC | error.code, message, data | Distinguer les problèmes de protocole, de méthode, de paramètre et d'autorisation |
| Outil MCP | result.isError et structuredContent | Un HTTP 200 peut néanmoins correspondre à un échec |
| Résultat métier | État réel, complétude, raison de l'échec, nextAction | Réceptionné ou prêt ne signifie pas terminé |
| Éligibilité factuelle | executionReceipt citationEligible contentComplete | Le contenu non éligible sert uniquement au repérage ou à l'explication des lacunes |
Cas HTTP courants
- 401 : Bearer absent ou expiré ; rafraîchissez le Token ou réautorisez selon le flux OAuth actuel.
- 403 : Grant, rôle, ressource sélectionnée, permission de source, Origin ou configuration non satisfaits ; ne tentez pas de contourner le refus par un rejeu.
- 400 : message ou contrat versionné invalide, y compris incohérence entre en-têtes modernes et métadonnées.
- 404 : vérifiez le chemin de service exact, la méthode du protocole et les capacités du runtime ; ne changez pas d'ID d'ontologie au hasard.
- 405 : le GET et le DELETE du /mcp public ne sont pas ouverts par conception ; utilisez le bon POST au lieu d'établir une connexion SSE persistante.
Opérations d'écriture au résultat incertain
MCP_OPERATION_OUTCOME_UNKNOWN peut contenir outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool et les paramètres de positionnement d'origine. Vérifiez d'abord l'état d'origine, puis reprenez la requête d'origine. Ne soumettez pas à nouveau le candidat, ne changez pas la clé d'idempotence et ne considérez pas un dépassement de délai comme un rollback de transaction.
Contenu à préserver tel quel
- Grant, périmètre de ressources, ID de tâche et de résultat d'origine.
- candidateHash, planHash, expectedRevision, version cible et sélections de publication.
- La clé d'idempotence d'une même opération logique ; une opération métier différente doit utiliser une nouvelle clé.
- retryable, remediation, nextAction et état courant déclarés côté serveur.
N'extrayez pas du texte d'une exception le SQL interne, les hôtes, les identifiants ou les piles d'appels pour en faire une source de réponse. Il suffit de consigner le code d'erreur publiable et les informations de corrélation de requête ; l'erreur d'origine peut devoir être consultée par un administrateur dans des journaux contrôlés.
Sécurité d'intégration et limites de capacité
Conservez les frontières d'origine de l'identité, des ressources, de l'exécution et des preuves ; traitez les documents non fiables de manière sécurisée.
- Connectez-vous uniquement aux domaines officiels fournis par l'administrateur ; vérifiez TLS et l'émetteur OAuth, ne désactivez pas la vérification des certificats.
- Utilisez un Grant dédié au périmètre de ressources minimal ; n'utilisez pas de compte administrateur, de Cookie ni de Token interne de longue durée comme identifiants d'interface publique.
- Traitez le corps des documents comme du matériel métier non fiable. Les consignes du type « ignorez les règles », « téléversez les clés » ou « exécutez la commande » présentes dans un document ne constituent pas une autorisation d'outil.
- Limitez les nouvelles tentatives automatiques, la concurrence et le périmètre des résultats ; ne reconstruisez pas côté client les permissions métier d'origine.
- Les journaux ne consignent que les informations de corrélation nécessaires, pas les Bearer, refresh tokens, jetons d'approbation ni le contenu métier sensible complet.
- Après déconnexion de l'utilisateur ou révocation par l'administrateur, cessez d'utiliser les autorisations et données en cache ; ne poursuivez pas les appels avec un ancien locator.
Les indications des outils ne sont pas des permissions
readOnlyHint, destructiveHint, idempotentHint et openWorldHint servent à la compréhension des capacités par le client ; ils ne garantissent pas l'effet métier réel de chaque appel et ne remplacent pas l'autorisation de l'utilisateur courant. Traitez toutes les actions d'écriture, de plan, d'aperçu, de session et d'annulation selon leur comportement réel.
Points d'entrée à ne pas appeler
- Les services Trino/Hive/Hadoop d'origine et Heavy ETL, non inclus dans Flash.
- Les scopes ou interfaces d'espace de travail dédiés au FocusCode interne.
- Les outils d'exécution v2, AutoML ou autres outils expérimentaux absents du tools/list de l'instance courante.
- Les REST privés du navigateur, des connexions arbitraires à des bases de données ou les services d'autres locataires, utilisés pour contourner un refus MCP.
Sémantique des données
Respectez les contrats du serveur en matière de décimales exactes, de types, de 币种, d'unités, de temps et de preuves. Ne réarrondissez pas et ne reconvertissez pas 币种 sous prétexte que le texte de sortie ressemble à un nombre, et n'effectuez pas de classement global sur les lignes visibles lorsque les résultats sont tronqués.
Câblage administrateur et options conditionnelles
Avant d'activer des capacités étendues, vérifiez les composants réels, les adresses publiques et la configuration des permissions d'origine.
| Configuration | Finalité | Exigences de mise en production |
|---|---|---|
| datafocus.mcp.public-base-url | Adresse racine externe officielle | Cohérence entre découverte OAuth, issuer, rappel et proxy inverse |
| datafocus.mcp.allowed-origins | Origines de navigateur supplémentaires approuvées | Configuration précise, sans élargir à des origines arbitraires |
| datafocus.mcp.oauth.route-proof-secret | Secret serveur dédié pour la preuve de routage du graphe | Stockage distinct, sans utiliser le Bearer comme clé |
| datafocus.mcp.analysis.tools.enabled | Outils d'analyse interactive | Services de données, de connaissances et de permissions associés réellement disponibles |
| datafocus.mcp.analysis.report-tools.enabled | Outils de rapports persistants | Stockage, worker et chaîne de reprise associés disponibles |
| datafocus.mcp.analysis.apps.enabled | Affichage MCP Apps | Déclaration de prise en charge par le client et vérification du _meta renvoyé |
| datafocus.mcp.authoring.enabled | Contrats de brouillon et de modélisation | Conservation des permissions administrateur et de ressources d'origine |
| datafocus.mcp.authoring.apply-enabled | Capacité d'application des artefacts | Plan immuable, approbation d'origine et revérification de l'état courant |
| datafocus.mcp.ontology-published-query-enabled | Modèle publié et requêtes | Version réelle à l'état committed et autorisation de source |
| datafocus.mcp.ontology-candidate-query-enabled | Requête structurée sur les candidats | Propriété du candidat, version précise et droit de lecture |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Autorisations liées à la délégation de publication automatique | Politique d'origine valide, confiance par clé publique, budget et droit de publication |
Ces noms proviennent de la configuration r56 et de l'implémentation ; la possibilité de les activer dépend des services associés et des contrôles de mise en production d'origine. Modifier uniquement des booléens ne fournira pas les processeurs, bases de données, budgets de validation ou politiques manquants. La visibilité des extensions d'entrée de connaissance et des tâches Pi dépend des composants réellement installés.
Proxy de bordure
Conservez Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name et l'Origin approuvé. Définissez le corps de requête, les délais d'attente et TLS selon les exigences réelles du service ; ne transférez pas le /mcp public vers un port d'administration ou un autre produit.
Liste de vérification de mise en production
- Les états de la découverte anonyme et des appels protégés correspondent aux attentes.
- Les utilisateurs ordinaires ne découvrent que leur périmètre autorisé ; après révocation, les requêtes suivantes sont refusées.
- Les sessions natives Search, le SQL, le texte original et les rapports optionnels produisent chacun des résultats réels.
- Les approbations d'écriture et de publication ainsi que la reprise idempotente conservent le comportement d'origine.
- Les journaux et la documentation publique ne contiennent ni clés privées, ni Token, ni Cookie, ni mots de passe, ni données clients internes.
Client exécutable et exemples d'appel
Validez les messages avec le client minimal fourni, sans contourner OAuth ni l'autorisation courante.
examples/flash_mcp.py est un client de protocole minimal reposant uniquement sur la bibliothèque standard Python. Il ne se connecte pas, n'approuve pas à votre place, n'appelle pas automatiquement des outils invisibles ; il prend en charge les protocoles moderne et ancien et se termine avec un code distinct selon la couche d'erreur : HTTP, JSON-RPC ou outil. Le Token est fourni via l'environnement du processus, jamais écrit dans un script ou un fichier de documentation.
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_TOKENLecture et requêtes
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.jsonRemplacez d'abord les espaces réservés tels que ONTOLOGY_ID et TABLE_RESOURCE_ID du fichier de requête par les valeurs réelles renvoyées par l'autorisation courante. Le client refuse de s'exécuter en présence d'espaces réservés. L'exemple SQL suppose que le CSV fourni a été importé avec les noms de colonnes d'origine ; en l'absence du schéma correspondant, la soumission directe est impossible.
Autres scénarios
- Point d'entrée métier : utilisez --endpoint business et obtenez un nouveau Grant destiné à /mcp/business.
- Ancien client : choisissez --protocol 2025-11-25, exécutez d'abord initialize, puis appelez avec le même protocole.
- Documentation intégrée : utilisez resources ou read-resource pour lire l'URI réel.
- Auto-test hors ligne : --self-test vérifie la construction des en-têtes modernes et des métadonnées, sans Token ni requête vers le serveur du produit.
Limites de l'exemple
Le client est un point de départ pour l'intégration du protocole ; il ne génère pas automatiquement de candidats de modélisation, n'enregistre pas de questions-réponses et n'exécute pas de publication. Il affiche le JSON brut afin que l'Agent de niveau supérieur vérifie l'état métier ; ne promettez pas à l'utilisateur l'achèvement d'une requête, d'un rapport ou d'une publication sur la seule base du code de sortie du processus.
Intégration de l'interface de dialogue d'ontologie
Intégrez la page de dialogue humaine dans le front-end métier en conservant les frontières de sécurité de connexion et du navigateur.
<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 est un ID de locataire d'exemple, 1001 un ID d'ontologie d'exemple ; remplacez-les à l'usage par des coordonnées réelles pour lesquelles vous disposez des droits. Une ontologie unique peut être désignée par path ou par un paramètre de requête (query) pris en charge ; le mode all fournit @ pour sélectionner les ontologies accessibles à l'utilisateur courant. skillId est simplement transmis tel quel ; n'en déduisez pas que l'orchestration de compétences est déjà exécutable.
Authentification et domaines
La page intégrée dépend d'un état de connexion DataFocus réel et vérifie /uc/status. Les Cookies inter-sites, SSO, les frame-ancestors CSP et la configuration de la passerelle influencent tous l'intégration. Elle n'accepte pas d'injecter un Bearer MCP dans l'URL comme canal de connexion sans authentification ; ne construisez pas vous-même, d'après des propositions de conception, les liens externes outside non implémentés.
Différence entre MCP et iframe
| Mode | Utilisateur | Identité et résultat |
|---|---|---|
| Remote MCP | Intégration d'Agent externe ou de service | Grant OAuth et reçus d'outils structurés |
| iframe de dialogue d'ontologie | Utilisateur final humain | État de connexion d'origine et interface de dialogue |
| MCP Apps | Client MCP prenant en charge l'extension | Ressources contrôlées et résultats d'outils actuels, et non un substitut public à la connexion via iframe |
Liste de contrôle de validation de l'intégration
Prouvez la chaîne métier complète sur une instance réelle, au lieu de vous contenter de vérifier que les interfaces renvoient 200.
- Découverte : obtenir les versions réellement prises en charge, le catalogue d'outils actuel et les ressources intégrées.
- Autorisation : les utilisateurs standard ne voient que les ontologies et systèmes métier autorisés ; les opérations sans scope sont refusées.
- Structure des tables : noms d'affichage réels, colonnes, types et permissions complets.
- SQL : les contrôles unidimensionnels, multidimensionnels, JOIN, dates, TopN et troncature sont conformes aux définitions métier réelles.
- Connaissances : repérage, texte original complet et éligibilité à la citation factuelle sont cohérents ; les questions mixtes s'appuient à la fois sur des données et sur des documents.
- Search : modèle, init, suggestions, résultats, fermeture et contrôles de complétude du tampon validés.
- Analyses et rapports optionnels : l'état réel des branches multiples, la pagination, les changements de permissions et l'annulation conservent le comportement d'origine.
- Modélisation optionnelle : candidat, plan, approbation d'origine, application effective et requête de version vérifiés étape par étape.
- Actions métier : hachage de publication, version cible, approbation, idempotence et isolation entre Grants vérifiées.
- Reprise : après un délai d'attente réseau, l'état d'origine est récupéré ; après une mise à jour de la source, l'ancien repérage devient invalide et une nouvelle requête est utilisée.
Enregistrement des résultats
Enregistrer la version de l'instance, les rôles des utilisateurs, le périmètre du Grant, la version de configuration, les opérations réelles et les résultats. Marquer séparément l'autocontrôle hors ligne du client de protocole, les valeurs attendues hors ligne de l'exemple CSV, la validation statique du schéma JSON et la véritable validation fonctionnelle en ligne. Ne pas extrapoler la réussite d'une phase en une réussite complète du produit.
Ressources de spécification et maintenance
Utilisez les schémas d'outils complets fournis avec le manuel et maintenez-les synchronisés avec les résultats de découverte réels de l'instance.
| Ressources | Contenu |
|---|---|
| reference/mcp-tool-catalog.json | Schémas d'entrée déclarés de 32 outils côté ontologie et de 8 outils côté métier ; certains outils incluent le schéma de sortie d'origine |
| reference/locales.json | 21 options sélectionnables, 24 locales compatibles et terminologie UI |
| reference/search-keywords.json | Catalogue statique de mots-clés pour 17 locales explicites |
| reference/analysis-contract-manifest.json | Contraintes de version liées aux analyses, branches, faits, reçus et rapports |
| examples/ | CSV synthétiques, notes sur les définitions métier, SQL Top3, résultats attendus et client de protocole minimal |
Ressources de documentation intégrées
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list et resources/read exigent que l'utilisateur actuel possède au moins une des qualifications de lecture correspondantes parmi metadata, search operate ou etl operate. Les documents ETL constituent une référence statique inter-produits ; les capacités exécutables de Flash restent limitées au périmètre qu'il déclare explicitement.
Références externes au protocole
Pour le protocole MCP et le contexte d'autorisation, se référer aux spécifications officielles : https://modelcontextprotocol.io/specification/2026-07-28/basic et https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. Les points de terminaison, outils et comportements conditionnels de ce produit sont basés sur l'implémentation r56 et les résultats de découverte de l'instance actuelle ; la prise en charge générique du protocole ne doit pas être assimilée à la fourniture de toutes les fonctionnalités optionnelles par le serveur.
Maintenance des mises à niveau
Lors des mises à niveau, redécouvrir les outils et les versions et comparer les schémas d'entrée, les contrats de sortie et la configuration ; les anciens Grants n'acquièrent pas automatiquement les nouveaux scopes. Maintenir les références, caches et reçus liés à la version source ; après confirmation de changements incompatibles, réobtenir le contexte et ne pas appliquer de force les anciennes localisations à de nouveaux états métier.
Référence des paramètres d'outils : base et Search natif
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfc_manual
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| names | array | Optionnel ou requis sous condition | Noms explicites à rechercher, 32 au maximum par appel. maxItems : 32 |
| action | string | Optionnel ou requis sous condition | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : list, read, keywords, functions, etl_requests |
| locale | string | Optionnel ou requis sous condition | Locale explicite du catalogue de référence statique, et non la langue par défaut des requêtes. |
| uri | string | Optionnel ou requis sous condition | URI des ressources intégrées listées par l'outil actuel. enum : datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| data | object | Optionnel ou requis sous condition | Charge utile de l'action d'origine ; se référer à la découverte de capacités et au tableau des champs d'action. |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| data | object | Optionnel ou requis sous condition | Charge utile de l'action d'origine ; se référer à la découverte de capacités et au tableau des champs d'action. |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : capabilities |
dfc_ontologies
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| pageSize | integer | Optionnel ou requis sous condition | Nombre d'éléments par page ; selon la limite du schéma. minimum : 1 ; maximum : 100 |
| page | integer | Optionnel ou requis sous condition | Numéro de page, à partir de 1. minimum : 1 |
dfc_ontology_resources
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| resourceTypes | array | Optionnel ou requis sous condition | Ensemble de types de ressources à renvoyer. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| pageSize | integer | Optionnel ou requis sous condition | Nombre d'éléments par page ; selon la limite du schéma. minimum : 1 ; maximum : 100 |
| page | integer | Optionnel ou requis sous condition | Numéro de page, à partir de 1. minimum : 1 |
Référence des paramètres d'outils : tables, graphe et connaissances
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfc_ontology_graph
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| relationTypes | array | Optionnel ou requis sous condition | Filtre de types de relations. |
| depth | integer | Optionnel ou requis sous condition | Profondeur de parcours des voisins. minimum : 1 ; maximum : 3 |
| sourceTypes | array | Optionnel ou requis sous condition | Filtre de types de sources. |
| query | object | Optionnel ou requis sous condition | Texte de requête, ou objet de requête versionné précis correspondant à action. |
| limit | integer | Optionnel ou requis sous condition | Limite du nombre de résultats renvoyés. minimum : 1 ; maximum : 100 |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| nodeKey | string | Optionnel ou requis sous condition | Clé de nœud copiée depuis un résultat réel du graphe. |
| keyword | string | Optionnel ou requis sous condition | Mot-clé de localisation dans le graphe, et non syntaxe de questions par mots-clés. |
| nodeTypes | array | Optionnel ou requis sous condition | Filtre de types de nœuds. |
dfc_ontology_query
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| routeLocators | array | Optionnel ou requis sous condition | Localisateurs de routage typés émis par le serveur, à copier intégralement. maxItems : 20 |
| topK | integer | Optionnel ou requis sous condition | Nombre maximal de candidats récupérés ; ne prouve pas que la couverture est complète. minimum : 1 ; maximum : 20 |
| queryMode | string | Optionnel ou requis sous condition | Mode de requête de preuve à choisir selon l'énumération de l'outil. enum : vector, hybrid, graph |
| fanoutPlan | object | Optionnel ou requis sous condition | Plan de recherche de branches restreint, selon le schéma imbriqué. |
| structuredPlan | object | Optionnel ou requis sous condition | Plan lié au contrat serveur d'un tableau de documents complet, et non SQL. |
| knowledgeIds | array | Optionnel ou requis sous condition | ID de base de connaissances issu des knowledgeBindings réels. |
| query | string | Requis | Texte de requête, ou objet de requête versionné précis correspondant à action. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
dfc_knowledge_search
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| topK | integer | Optionnel ou requis sous condition | Nombre maximal de candidats récupérés ; ne prouve pas que la couverture est complète. minimum : 1 ; maximum : 20 |
| minScore | number | Optionnel ou requis sous condition | Score de correspondance minimal. minimum : 0 ; maximum : 1 |
| knowledgeIds | array | Optionnel ou requis sous condition | ID de base de connaissances issu des knowledgeBindings réels. |
| query | string | Requis | Texte de requête, ou objet de requête versionné précis correspondant à action. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| assetIds | array | Optionnel ou requis sous condition | ID d'actifs documentaires actuellement autorisés. |
| retrievalStrategy | string | Optionnel ou requis sous condition | Stratégie de recherche réellement prise en charge. enum : auto, hybrid_stage2 |
dfc_knowledge_detail
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| qdrantId | string / integer | Optionnel ou requis sous condition | Identifiant d'index renvoyé par le repérage réel. |
| pageNo | integer | Optionnel ou requis sous condition | Numéro de page ou de pagination réel. |
| evidenceId | string | Optionnel ou requis sous condition | ID de preuve renvoyé pour la même localisation de connaissances. |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : chunk, document, page_context |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| documentId | string / integer | Optionnel ou requis sous condition | ID du document pour la même localisation. |
| radius | integer | Optionnel ou requis sous condition | Plage de pages adjacentes. minimum : 0 ; maximum : 3 |
| chunkId | string | Optionnel ou requis sous condition | ID de fragment réel pour la même localisation. |
dfc_table
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| maxRows | integer | Optionnel ou requis sous condition | Limite du nombre de lignes renvoyées ; ce n'est pas une plage de classement côté client. minimum : 1 ; maximum : 200 |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : detail, query |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| id | string | Optionnel ou requis sous condition | ID de ressource de table réel, et non nom physique ni nom d'affichage. |
| sql | string | Optionnel ou requis sous condition | Une seule instruction SQL Doris en lecture seule dans le périmètre de l'ontologie, avec colonnes de sortie explicites. |
Référence des paramètres d'outils : analyses et rapports
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfc_analysis_ask
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| question | string | Requis | Question en langage naturel ou question de suivi compatible. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| language | string | Optionnel ou requis sous condition | Locale explicite de la réponse ou de la requête ; si elle est omise, les règles de l'outil concerné s'appliquent. |
| sessionId | string | Optionnel ou requis sous condition | Localisateur de session réel relevant du même Grant. |
dfc_analysis_refine
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| branchId | string | Optionnel ou requis sous condition | Localisateur de branche structurée émis par le serveur. |
| resultId | string | Requis | Localisateur du résultat d'analyse renvoyé à l'origine. |
| question | string | Optionnel ou requis sous condition | Question en langage naturel ou question de suivi compatible. |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| change | object | Optionnel ou requis sous condition | Modification en langage naturel ou filter_patch typé. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| language | string | Optionnel ou requis sous condition | Locale explicite de la réponse ou de la requête ; si elle est omise, les règles de l'outil concerné s'appliquent. |
| sessionId | string | Requis | Localisateur de session réel relevant du même Grant. |
| expectedRevision | integer | Requis | Précondition de version du résultat ou de l'en-tête métier d'origine ; peut être null lors de la création d'une question. minimum : 1 |
| visualId | string | Optionnel ou requis sous condition | Localisateur de visualisation lié à la branche. |
dfc_analysis_page
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| branchId | string | Requis | Localisateur de branche structurée émis par le serveur. |
| resultId | string | Requis | Localisateur du résultat d'analyse renvoyé à l'origine. |
| pageNo | integer | Requis | Numéro de page ou de pagination réel. minimum : 1 ; maximum : 10000 |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| pageSize | integer | Requis | Nombre d'éléments par page ; selon la limite du schéma. minimum : 1 ; maximum : 100 |
| sessionId | string | Requis | Localisateur de session réel relevant du même Grant. |
| expectedRevision | integer | Requis | Précondition de version du résultat ou de l'en-tête métier d'origine ; peut être null lors de la création d'une question. minimum : 1 |
dfc_analysis_result_get
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| resultId | string | Requis | Localisateur du résultat d'analyse renvoyé à l'origine. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| sessionId | string | Requis | Localisateur de session réel relevant du même Grant. |
dfc_analysis_cancel
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| resultId | string | Requis | Localisateur du résultat d'analyse renvoyé à l'origine. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| sessionId | string | Requis | Localisateur de session réel relevant du même Grant. |
dfc_analysis_close
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| sessionId | string | Requis | Localisateur de session réel relevant du même Grant. |
dfc_report_create
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| goal | string | Requis | Cible d'analyse du rapport. |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| language | string | Optionnel ou requis sous condition | Locale explicite de la réponse ou de la requête ; si elle est omise, les règles de l'outil concerné s'appliquent. |
| title | string | Optionnel ou requis sous condition | Titre de rapport optionnel. |
dfc_report_status
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| reportId | string | Requis | Localisateur de rapport persistant du Grant actuel. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
dfc_report_cancel
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| reportId | string | Requis | Localisateur de rapport persistant du Grant actuel. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
Référence des paramètres d'outils : modélisation et tâches d'origine
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfc_ontology_agent
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| mode | string | Optionnel ou requis sous condition | QUERY ou AUTHORING ; chaque capacité est autorisée séparément. enum : QUERY, AUTHORING |
| instruction | string | Optionnel ou requis sous condition | Texte de la demande de l'utilisateur ; à garder identique entre le contexte et la soumission. maxLength : 16000 |
| idempotencyKey | string | Optionnel ou requis sous condition | Clé d'idempotence réutilisée de manière stable pour la même opération logique. maxLength : 128 |
| action | string | Requis | Nom de l'opération. À utiliser selon l'énumération actuelle et les paramètres correspondant à l'action. enum : start, status, cancel |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| runId | string | Optionnel ou requis sous condition | ID de la tâche d'origine pour la même ontologie et le même Grant. |
| contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. enum : ontology-agent-task-v1 |
dfc_authoring_capabilities
L'objet racine d'entrée de cet outil n'a aucun champ ; utiliser un objet arguments vide.
dfc_artifact_context
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Optionnel ou requis sous condition | Type de périmètre de ressources dans le contrat d'artefact réel. |
| ontologyId | string | Optionnel ou requis sous condition | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| projectId | string | Optionnel ou requis sous condition | ID du projet actuellement autorisé. |
| artifactId | string | Optionnel ou requis sous condition | ID réel de l'artefact existant à modifier. |
| instruction | string | Requis | Texte de la demande de l'utilisateur ; à garder identique entre le contexte et la soumission. |
| variables | object | Optionnel ou requis sous condition | Objet de variables fourni selon le contrat renvoyé. |
| previewInput | object | Optionnel ou requis sous condition | Entrée de prévisualisation bornée fournie selon le contrat. |
| viewport | object | Optionnel ou requis sous condition | Viewport d'affichage exigé par le contrat d'origine. |
dfc_ontology_table_schema
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| sourceAssetRef | string | Requis | Référence d'actif structuré enregistrée, par exemple table:123. |
| fields | array | Requis | Champs de la source actuelle avec déclarations de types optionnelles explicites. minItems : 1 ; maxItems : 64 |
dfc_artifact_preview
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| proposalId | string | Requis | ID du candidat d'origine créé dans le Grant actuel. |
| candidateHash | string | Requis | Hachage exact du candidat côté serveur d'origine. |
| previewInput | object | Requis | Entrée de prévisualisation bornée fournie selon le contrat. |
dfc_artifact_status
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| proposalId | string | Optionnel ou requis sous condition | ID du candidat d'origine créé dans le Grant actuel. |
| planId | string | Optionnel ou requis sous condition | ID du plan d'application immuable. |
dfc_artifact_plan
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| proposalId | string | Requis | ID du candidat d'origine créé dans le Grant actuel. |
| candidateHash | string | Requis | Hachage exact du candidat côté serveur d'origine. |
| expectedTargetVersion | integer | Requis | Précondition de version cible réelle actuelle. minimum : 0 |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
dfc_artifact_apply
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| planId | string | Requis | ID du plan d'application immuable. |
| planHash | string | Requis | Hachage renvoyé par le plan d'origine. |
| approvalToken | string | Requis | Éléments d'approbation émis par le serveur d'origine ; ne les générez jamais vous-même. |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
dfc_artifact_submit
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| Configuration 1 / artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : CONTROL_PANEL_SPEC, VIEW_SPEC |
| Configuration 1 / scopeType | string | Optionnel ou requis sous condition | Type de périmètre de ressources dans le contrat d'artefact réel. |
| Configuration 1 / ontologyId | string | Optionnel ou requis sous condition | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| Configuration 1 / projectId | string | Optionnel ou requis sous condition | ID du projet actuellement autorisé. |
| Configuration 1 / artifactId | string | Optionnel ou requis sous condition | ID réel de l'artefact existant à modifier. |
| Configuration 1 / instruction | string | Requis | Texte de la demande de l'utilisateur ; à garder identique entre le contexte et la soumission. |
| Configuration 1 / variables | object | Optionnel ou requis sous condition | Objet de variables fourni selon le contrat renvoyé. |
| Configuration 1 / previewInput | object | Optionnel ou requis sous condition | Entrée de prévisualisation bornée fournie selon le contrat. |
| Configuration 1 / viewport | object | Optionnel ou requis sous condition | Viewport d'affichage exigé par le contrat d'origine. |
| Configuration 1 / contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. |
| Configuration 1 / contextHash | string | Requis | Hachage du contexte complet renvoyé par context. |
| Configuration 1 / baseArtifactHash | string | Requis | Hachage de l'artefact de base renvoyé par context. |
| Configuration 1 / baseArtifactVersion | integer | Requis | Version de base renvoyée par context. minimum : 0 |
| Configuration 1 / candidate | object | Requis | Objet candidat conforme au contrat actuellement renvoyé. |
| Configuration 1 / clientRequestId | string | Requis | Clé d'idempotence client utilisée de manière stable pour la requête de candidat en cours. |
| Configuration 2 / artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : ONTOLOGY_RELEASE |
| Configuration 2 / contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. 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 |
| Configuration 2 / ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| Configuration 2 / candidateHash | string | Requis | Hachage exact du candidat côté serveur d'origine. |
| Configuration 2 / workspaceId | string | Requis | Coordonnées réelles de l'espace de travail du candidat. |
| Configuration 2 / workspaceRevision | string | Requis | Version exacte du candidat, sans utiliser latest. |
| Configuration 2 / releases | object | Requis | Sélections de versions exactes fournies selon le contrat de publication d'ontologie. |
| Configuration 2 / selection | object | Requis | Fournir uniquement les coordonnées de sélection métier explicites, sans preuve d'autorisation ni d'achèvement. |
| Configuration 2 / idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| Configuration 3 / Configuration 1 / artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : ONTOLOGY_RELEASE |
| Configuration 3 / Configuration 1 / contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. enum : ontology-workspace-create-mcp-submit-v1 |
| Configuration 3 / Configuration 1 / ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| Configuration 3 / Configuration 1 / workspaceId | string | Requis | Coordonnées réelles de l'espace de travail du candidat. |
| Configuration 3 / Configuration 1 / resources | array | Requis | Déclarations de modèle d'origine, compilées par le serveur. minItems : 1 |
| Configuration 3 / Configuration 1 / idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| Configuration 3 / Configuration 2 / artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : ONTOLOGY_RELEASE |
| Configuration 3 / Configuration 2 / contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. enum : ontology-workspace-create-mcp-submit-v2 |
| Configuration 3 / Configuration 2 / ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| Configuration 3 / Configuration 2 / workspaceId | string | Requis | Coordonnées réelles de l'espace de travail du candidat. |
| Configuration 3 / Configuration 2 / resources | array | Requis | Déclarations de modèle d'origine, compilées par le serveur. minItems : 1 |
| Configuration 3 / Configuration 2 / idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| Configuration 3 / Configuration 2 / releaseSelections | object | Requis | releaseId exact de chaque référence publiée et fermeture des dépendances. |
| Configuration 4 / artifactType | string | Requis | Type d'artefact ou de publication d'ontologie réellement activé. enum : ONTOLOGY_RELEASE |
| Configuration 4 / contractVersion | string | Requis | Vous devez utiliser la version exacte du contrat réellement prise en charge. enum : ontology-initial-activation-retirement-submit-v1 |
| Configuration 4 / ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| Configuration 4 / domainRid | string | Requis | RID réel du domaine métier. |
| Configuration 4 / consumerScopes | array | Requis | Périmètres consommateurs exacts autorisés par le serveur. minItems : 1 ; maxItems : 256 |
| Configuration 4 / idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
Référence des paramètres d'outils : saisie des connaissances et périmètre
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfc_ontology_knowledge_input_propose
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| request | object | Requis | Requête d'entrée métier d'origine ; selon le schéma imbriqué complet. |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. minLength : 1 ; maxLength : 128 |
Cet outil dispose également d'un outputSchema natif. Vérifiez la complétude et l'état de la sortie ainsi que les champs d'autorisation explicitement définis à false ; n'attribuez pas de vous-même à la sortie un sens d'achèvement plus fort.
dfc_ontology_knowledge_input_preview
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. minLength : 1 ; maxLength : 128 |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
Cet outil dispose également d'un outputSchema natif. Vérifiez la complétude et l'état de la sortie ainsi que les champs d'autorisation explicitement définis à false ; n'attribuez pas de vous-même à la sortie un sens d'achèvement plus fort.
dfc_ontology_knowledge_question_submit
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| questionRevision | $ref | Requis | Version explicite de la question à confirmer. |
| idempotencyKey | $ref | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. |
| originalInputKey | $ref | Requis | Clé d'idempotence correspondant à l'entrée de connaissances d'origine. |
| ontologyId | string | Requis | ID d'ontologie réel dans la présente autorisation, conservé sous forme de chaîne. |
| validUntil | $ref | Requis | Fin de la fenêtre de validité de la question, heure UTC. |
| expectedRevision | oneOf | Requis | Précondition de version du résultat ou de l'en-tête métier d'origine ; peut être null lors de la création d'une question. |
| validFrom | $ref | Requis | Début de la fenêtre de validité de la question, heure UTC. |
Cet outil dispose également d'un outputSchema natif. Vérifiez la complétude et l'état de la sortie ainsi que les champs d'autorisation explicitement définis à false ; n'attribuez pas de vous-même à la sortie un sens d'achèvement plus fort.
dfc_ontology_business_scope_initialize
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| domainRevisionId | string | Requis | Version exacte du domaine métier. minLength : 1 ; maxLength : 128 |
| idempotencyKey | string | Requis | Clé d'idempotence réutilisée de manière stable pour la même opération logique. minLength : 1 ; maxLength : 128 |
| businessSystemId | string | Requis | ID réel du système métier. minLength : 1 |
| ontologyId | string | Requis | ID réel de l'ontologie dans la présente autorisation, conservé sous forme de chaîne. minLength : 1 |
| domainRid | string | Requis | RID réel du domaine métier. minLength : 1 ; maxLength : 128 |
Cet outil dispose également d'un outputSchema natif. Vérifiez la complétude et l'état de la sortie ainsi que les champs d'autorisation explicitement définis à false ; n'attribuez pas de vous-même à la sortie un sens d'achèvement plus fort.
Référence des paramètres d'outils : espace de travail métier
Noms complets et champs d'entrée, à consulter par outil.
Les tableaux suivants constituent une référence de lecture des champs d'entrée des outils r56 actuels. Pour les types imbriqués complets, oneOf, champs requis sous condition, contraintes de motif et certains schémas de sortie, voir reference/mcp-tool-catalog.json ; avant toute soumission finale, il faut toujours lire le tools/list du Grant actuel. La mention « optionnel » dans les tableaux ne lève pas les exigences de validation internes aux actions.
dfb_systems
L'objet racine d'entrée de cet outil n'a aucun champ ; utiliser un objet arguments vide.
dfb_system_describe
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| systemId | string / integer | Requis | ID de système autorisé par le présent Grant métier. |
dfb_query
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| systemId | string / integer | Requis | ID de système autorisé par le présent Grant métier. |
| queryKey | string | Requis | Clé de requête publiée renvoyée par describe. |
| objectKey | string | Optionnel ou requis sous condition | Clé d'objet publiée. |
| pageSize | integer | Optionnel ou requis sous condition | Nombre d'éléments par page ; selon la limite du schéma. minimum : 1 ; maximum : 100 |
| page | integer | Optionnel ou requis sous condition | Numéro de page, à partir de 1. minimum : 1 |
| state | string | Optionnel ou requis sous condition | Filtre d'état métier ou état côté serveur. |
dfb_record
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| recordId | string / integer | Requis | ID de l'enregistrement métier dont la lecture est actuellement autorisée. |
| systemId | string / integer | Requis | ID de système autorisé par le présent Grant métier. |
dfb_work_items
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| systemId | string / integer | Requis | ID de système autorisé par le présent Grant métier. |
dfb_action_plan
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| expectedRecordVersion | integer | Optionnel ou requis sous condition | Version actuelle du verrou optimiste de l'enregistrement cible. minimum : 1 |
| systemId | string / integer | Requis | ID de système autorisé par le présent Grant métier. |
| commandType | string | Requis | Type de commande du contrat publié. |
| canonicalIrHash | string | Requis | Hachage IR canonique de la publication actuelle. |
| releaseId | string / integer | Requis | ID réel de la version du contrat publié. |
| payload | object | Requis | Charge utile conforme au contrat de commande actuel décrit dans describe. |
| releaseHash | string | Requis | Hachage réel du contrat publié. |
| targetRecordId | string / integer | Optionnel ou requis sous condition | Enregistrement cible réel sur lequel l'opération doit porter. |
| agentManifestHash | string | Requis | Hachage réel du manifeste des capacités de l'Agent. |
| planIdempotencyKey | string | Requis | Clé d'idempotence stable du plan métier. |
dfb_action_status
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| actionPlanId | string / integer | Requis | ID du plan d'action détenu par le Grant métier actuel. |
dfb_action_execute
| Paramètre | Type | Requis | Signification et portée |
|---|---|---|---|
| approvalToken | string | Optionnel ou requis sous condition | Éléments d'approbation émis par le serveur d'origine ; ne les générez jamais vous-même. |
| actionPlanId | string / integer | Requis | ID du plan d'action détenu par le Grant métier actuel. |