Manual de integración de Agent y MCP de OT Flash
Protocolo, autorización, contratos de herramientas y flujo completo de invocación
Cree aplicaciones de datos y conocimiento trazables mediante el Remote MCP público de OT Flash r56. Este manual describe OAuth, los mensajes del protocolo, la referencia de parámetros de todas las herramientas declaradas, las reglas de evidencia, las capacidades condicionales y los flujos de recuperación, e incluye un cliente ejecutable y ejemplos de datos sintéticos.
Desarrolladores de Agents, ingenieros de integración y administradores
Los ejemplos incluidos conservan los nombres de campo en chino. La traducción de la interfaz y del texto explicativo no altera los nombres reales de tablas, columnas, valores de enumeración, herramientas ni campos de protocolo.
Índice
- 1Alcance de la integración del Agent y criterios de finalización
- 2Conexión rápida y descubrimiento de capacidades
- 3Descubrimiento, registro y autorización de OAuth
- 4Scope, límites de recursos y permisos en tiempo real
- 5Mensajes HTTP y del MCP moderno
- 6Compatibilidad con clientes del protocolo antiguo
- 7Elección de la herramienta y del canal de evidencia adecuados
- 8Recursos de ontología y tipos de ID
- 9Consulta de tablas Doris y contrato de estructura
- 10Top3 multidimensional y manejo de truncamiento
- 11Recuperación de conocimiento: texto original completo y elegibilidad de la evidencia
- 12Modelos y sesiones nativos de Search
- 13Convenciones de idioma y región
- 14Análisis integrado y resultados interactivos
- 15Informes visualizables persistentes y MCP Apps
- 16Borradores de artefactos: vista previa, plan y aplicación
- 17Contrato de creación y publicación de candidatos de ontología
- 18Modelo publicado, consulta de candidatos y clausura de referencias
- 19Delegación de tareas al agente de ontología
- 20MCP del espacio de trabajo de negocio
- 21Entradas de conocimiento de negocio y preguntas pendientes de confirmación
- 22Respuestas, errores y reintentos seguros
- 23Seguridad de la integración y límites de capacidad
- 24Configuración del administrador e interruptores condicionales
- 25Cliente ejecutable y ejemplos de llamada
- 26Incrustación de la interfaz de diálogo de la ontología
- 27Lista de verificación de aceptación de la integración
- 28Recursos de especificación y mantenimiento
- 29Referencia de parámetros de herramientas: básicas y Search nativo
- 30Referencia de parámetros de herramientas: tablas, grafo y conocimiento
- 31Referencia de parámetros de herramientas: análisis e informes
- 32Referencia de parámetros de herramientas: modelado y tareas originales
- 33Referencia de parámetros de herramientas: entrada de conocimiento y alcance
- 34Referencia de parámetros de herramientas: espacio de trabajo de negocio
Alcance de la integración del Agent y criterios de finalización
Seleccione el punto de entrada de autorización y complete consultas, obtención de evidencias o escrituras controladas según el recibo del servidor.
OT Flash r56 proporciona a los Agents externos capacidades de datos y conocimiento dentro del alcance de la ontología a través de Remote MCP, además de un punto de entrada independiente para el espacio de trabajo de negocio. El Agent debe determinar el trabajo ejecutable en función del tools/list real, de inputSchema, del scope de OAuth y de los permisos actuales sobre los recursos; no debe inferir de un manual estático que un despliegue ya tenga habilitadas todas las funciones opcionales.
| Entrada | Propósito | Límites |
|---|---|---|
| /mcp | Ontología, tablas de datos, conocimiento documental, Search nativo, y análisis y modelado disponibles de forma condicional | Intersección entre los permisos del usuario actual y los recursos incluidos en esta autorización |
| /mcp/business | Descubrimiento de sistemas de negocio, consultas, planes de acción, estado y ejecución | Autorización independiente de sistemas de negocio y contratos publicados |
| Página incrustada del agente de ontología | Uso del diálogo de ontología en la interfaz humana | Depende de una sesión iniciada real; no es un punto de entrada para obtener tokens MCP sin iniciar sesión |
Clasificación de capacidades
- Lectura básica: ontología y recursos, localización en el grafo, recuperación de conocimiento y texto original completo, detalles de tablas autorizadas y Doris SQL.
- Delegación independiente: dfc_search requiere search:operate y sigue usando los permisos originales del usuario y del modelo.
- Disponibilidad condicional: análisis, informes persistentes, borradores de artefactos y su aplicación, consultas al modelo de ontología y tareas delegadas al Agent.
- Capacidades no disponibles: el dfc_etl de Flash solo informa de capabilities y no ofrece ejecución de Heavy ETL. AutoML y el punto de entrada interno del espacio de trabajo FocusCode no forman parte de la API pública de Flash que describe este manual.
Criterios de finalización
Para leer hechos debe obtenerse un recibo real y utilizable de consulta o de texto original completo; al generar candidatos debe indicarse que aún no se han aplicado; publicar exige un recibo real con estado APPLIED; cancelar debe distinguir entre solicitud y confirmación. El texto de la respuesta, un HTTP 200, que la herramienta haya recibido la solicitud o una descripción del modelo de que la operación «se ha completado» no prueban por sí solos el éxito de una operación de negocio.
El reference/mcp-tool-catalog.json adjunto es una referencia declarativa fuera de línea de r56 e incluye definiciones de activación condicional, no el tools/list en tiempo real de ningún usuario. El catálogo completo comprende 28 herramientas centrales de ontología, 4 extensiones condicionales del controlador y 8 herramientas del lado de negocio, lo cual no implica que todo esté abierto por defecto.
Conexión rápida y descubrimiento de capacidades
Comience con el dominio oficial de la instancia y descubra las herramientas realmente disponibles con los permisos mínimos.
- Solicite al administrador la dirección raíz oficial de HTTPS y la ontología o el sistema de negocio a los que necesita acceder. No utilice los dominios de ejemplo de la documentación para llamar a sistemas de negocio reales.
- Configure la dirección del servidor de MCP como https://flash.example.com/mcp; el espacio de trabajo de negocio usa /mcp/business en el mismo dominio.
- Active el inicio de sesión y la autorización de OAuth según lo que admita el cliente y verifique los recursos y el scope; no envíe usuario y contraseña a MCP.
- Realice el descubrimiento o la inicialización con la generación de protocolo correspondiente y, a continuación, lea tools/list y las descripciones de recursos.
- Ejecute primero una pequeña petición de solo lectura, verifique los resultados estructurados y los errores y, después, cumpla el objetivo del usuario.
Fragmento de configuración del cliente
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}Este fragmento ilustra la intención de configuración de la dirección del servidor; la estructura concreta del archivo de configuración y la compatibilidad con OAuth dependen del cliente. No escriba access_token, refresh_token, Cookie ni contraseñas de administrador reales en archivos públicos.
Descubrimiento de protocolo moderno
POST /mcp HTTP/1.1
Host: flash.example.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}Comprobaciones previas al acceso
- La dirección raíz de recursos, el issuer de OAuth y la dirección externa del proxy inverso coinciden.
- El cliente admite la generación de protocolo correspondiente, en lugar de enviar siempre initialize al punto de entrada del protocolo nuevo.
- La autorización actual está vinculada a la ontología o al sistema de negocio necesarios.
- El token es válido y los nuevos scope opcionales se han autorizado explícitamente.
Descubrimiento, registro y autorización de OAuth
Utilice el código de autorización y PKCE; no exponga las credenciales de inicio de sesión del producto al Agent.
| Endpoint | Método | Función |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Descubrimiento del recurso MCP de ontología |
| /.well-known/oauth-protected-resource/mcp | GET | Descubrimiento compatible por ruta del recurso de ontología |
| /.well-known/oauth-protected-resource/mcp/business | GET | Descubrimiento del recurso MCP de negocio |
| /.well-known/oauth-authorization-server | GET | Metadatos del servidor de autorización |
| /oauth/register | POST JSON | Registro dinámico de public client |
| /oauth/authorize | Formulario GET o POST | Inicio de sesión, selección de recursos y confirmación de la autorización |
| /oauth/token | POST form | Canje del código de autorización y renovación con rotación |
| /oauth/revoke | POST form | Revocación de tokens |
| /oauth/grants | GET | El usuario autenticado consulta las conexiones autorizadas |
| /oauth/grants/revoke | POST form | Revocación de conexiones siguiendo el flujo de la página original |
Orden de autorización
- Lea los metadatos del recurso protegido y los metadatos del servidor de autorización. Una petición sin token que devuelva 401 y WWW-Authenticate apuntará a la dirección de descubrimiento de recursos.
- Registre o utilice una identidad de cliente. El registro dinámico de public client de r56 usa token_endpoint_auth_method=none; no se puede sustituir PKCE por un secreto de cliente.
- Genere un state y un code_verifier aleatorios y calcule el code_challenge de S256.
- Abra la dirección authorize indicada por los metadatos y transmita response_type=code, client_id, redirect_uri exacto, scope, resource, state, code_challenge y code_challenge_method=S256.
- El usuario inicia sesión en DataFocus y selecciona la ontología o el sistema de negocio. El cliente no puede preseleccionar recursos a los que el usuario no tenga acceso.
- Reciba la devolución de llamada y verifique state e issuer; canjee el código de autorización con el code_verifier original.
- Utilice el access_token únicamente para la autenticación Bearer de MCP. Para renovarlo, use el flujo original de OAuth y guarde de forma segura el refresh_token rotado.
Ejemplo de registro
{
"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"]
}La devolución de llamada de los clientes web usa HTTPS; los clientes nativos pueden usar direcciones de loopback admitidas. Tanto la autorización como el canje del token exigen una coincidencia exacta con la devolución de llamada registrada. Cada Grant corresponde a un único protected resource; no mezcle el scope de la ontología con el scope del espacio de trabajo de negocio en la misma conexión.
Ciclo de vida de los tokens
En el servidor de r56, por defecto el access token es de 3600 segundos, el refresh token de 2592000 segundos y el código de autorización de 300 segundos; el despliegue puede sobrescribir estos valores. El cliente debe guiarse por el expires_in de la respuesta de token y por los errores reales, sin fijar los valores por defecto en el código. Actualice el token tras la renovación; revocar un rol, un permiso de recurso o un Grant hará que las llamadas posteriores sean rechazadas.
Scope, límites de recursos y permisos en tiempo real
El alcance autorizado delega los permisos existentes; no concede escalada de roles ni comparte estado de negocio entre Grants.
| Scope | Capacidad típica | Restricción importante |
|---|---|---|
| ontology.metadata:read | Ontología, recursos y estructura de tablas | La ontología y las tablas deben estar autorizadas y ser legibles actualmente |
| ontology.graph:read | Búsqueda en el grafo y vecinos | Devuelve información de localización, no evidencia de hechos |
| ontology.knowledge:read | Localización de conocimiento y texto original completo | Conserva los permisos originales de la base de conocimiento y de los documentos |
| ontology.table:query | SQL de tablas de ontología y consultas al modelo publicado | La consulta de tablas requiere además el scope metadata; el origen real y los permisos de columna siguen aplicándose |
| search:operate | Modelos y sesiones nativos de palabras clave | Delegación explícita e independiente; se ejecuta según el modelo original y los permisos de tabla y columna del usuario |
| etl:operate | Capabilities de Flash ETL | No expone Heavy ETL |
| authoring.contract:read | Contratos de modelado disponibles de forma condicional | Requieren además el interruptor de función y los recursos correspondientes |
| authoring.artifact:read | Lectura de candidatos, planes, etc. de la autorización actual | Vinculado al Grant y a los recursos del sujeto original |
| authoring.artifact:draft | Envío de candidatos, vista previa, etc. | No autoriza ejecución ni publicación |
| authoring.artifact:apply | Planes controlados y aplicación | Siguen requiriendo el rol de negocio original, las políticas y las aprobaciones |
| execution.script:draft | Borradores de scripts específicos | No autoriza la ejecución real de scripts |
| datasource.http:read / draft / test / import | Capacidades de artefactos de fuentes de datos HTTP, disponibles de forma condicional | Cada una con su propio interruptor y los permisos originales |
Combinaciones de scope necesarias para la lectura
dfc_table detail requiere ontology.metadata:read; query requiere además ontology.table:query. dfc_ontology_query requiere los dos scope de lectura graph y knowledge. dfc_knowledge_search/detail requiere knowledge. published_model/published_query usan table:query; candidate_query requiere además authoring.artifact:read. Las herramientas de análisis comprueban además los scope de evidencia permitidos; los informes persistentes requieren metadata y table query.
No fije las autorizaciones por defecto en el código
El conjunto de scope por defecto de la ontología de r56 incluye table query; Search y ETL son delegaciones explícitas. Lo decisivo son siempre los metadatos de descubrimiento, la página de autorización, el scope real del token y tools/list. Las afirmaciones de documentación antigua como «la ontología por defecto nunca tiene SQL» o «solo hay seis herramientas» no deben tomarse como base de la implementación actual.
Aislamiento de estados
Las sesiones, los informes, los candidatos y los planes de acción tienen su propio propietario y alcance. La renovación del access token no transfiere el trabajo del Grant original a otro Grant. No fusione en la conexión actual sessionId, reportId, planId, tokens de aprobación ni tokens de origen devueltos por otra conexión.
Mensajes HTTP y del MCP moderno
Envíe correctamente los metadatos por petición y las cabeceras de ruta correspondientes, y trate por separado HTTP y los resultados de las herramientas.
| Elemento | Comportamiento de r56 |
|---|---|
| Transporte | Streamable HTTP sin estado, POST JSON-RPC |
| Identificadores admitidos | 2026-07-28 así como 2025-11-25 2025-06-18 2025-03-26 |
| Métodos modernos | server/discover, tools/list, tools/call, resources/list, resources/read, disponibles según las capacidades reales |
| Cabecera de sesión | No asigna Mcp-Session-Id |
| GET y DELETE | /mcp y /mcp/business devuelven 405 |
| Notificaciones SSE del servidor | No se ofrecen en estos dos puntos de entrada públicos de MCP |
| Caché del catálogo | El descubrimiento moderno y las respuestas de lista devuelven ttlMs=60000 y cacheScope=private |
| Resultado normal | El resultado moderno incluye resultType=complete y metadatos de identidad de servicio |
Contenido que debe coincidir
- MCP-Protocol-Version coincide con io.modelcontextprotocol/protocolVersion en params._meta.
- Mcp-Method coincide con el método JSON-RPC.
- Para tools/call, Mcp-Name coincide con params.name; para resources/read, la cabecera de nombre coincide con URI.
- Cada solicitud moderna incluye el objeto io.modelcontextprotocol/clientCapabilities; proporcione también el clientInfo estándar para facilitar la identificación del cliente.
Ejemplo de llamada
{
"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": {}
}
}
}Las cabeceras HTTP correspondientes son Mcp-Method: tools/call y Mcp-Name: dfc_ontologies. Todos los ACCESS_TOKEN de los ejemplos son marcadores de posición. No incluya el token Bearer en la URL, en los parámetros JSON ni en claves de caché.
Lectura de resultados
Procese primero el estado HTTP y luego compruebe el error JSON-RPC; si hay result, continúe comprobando isError. Los resultados de herramientas correctos suelen proporcionar structuredContent junto con contenido text que contiene el mismo JSON de negocio; lea preferentemente el canal estructurado y evite contar dos veces text y structuredContent como si fueran dos hechos independientes. Un HTTP 200 puede contener un fallo de herramienta.
Recursos públicos e interfaz de usuario
Los recursos de documentación integrados no dependen de MCP Apps. El punto de entrada del espacio de trabajo de negocio no obtiene por ello recursos de documentación de la ontología. Los clientes que admitan visualización deben descubrir la interfaz de usuario correspondiente mediante las capacidades reales y los _meta de las herramientas, sin adivinar los URI de recursos no devueltos.
Compatibilidad con clientes del protocolo antiguo
Mantenga una generación de protocolo coherente en los clientes que aún utilicen el handshake de inicialización.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Envíe initialize y lea la versión de protocolo y las capabilities negociadas por el servidor.
- Envíe la notificación de finalización de inicialización requerida según el protocolo del cliente; las notificaciones no producen resultados de herramienta normales.
- Use tools/list para leer las herramientas autorizadas actualmente y, a continuación, envíe tools/call.
- Mantenga la coherencia entre las cabeceras y los mensajes de la generación de protocolo de la solicitud actual; no envíe flujos initialize ni ping antiguos a mensajes 2026-07-28.
El protocolo antiguo sigue utilizando el mismo Bearer/OAuth, los mismos permisos y el mismo contrato de herramientas. No implica que el servidor ofrezca necesariamente conexiones persistentes SSE de estilo antiguo ni Mcp-Session-Id; el servicio público de r56 se mantiene sin estado.
Errores de protocolo
| Situación | Resultado típico | Solución |
|---|---|---|
| Las cabeceras modernas y el mensaje no coinciden | HTTP 400 JSON-RPC -32020 | Corrija las cabeceras, los metadatos y los nombres de las herramientas |
| Versión no compatible | -32022 junto con la lista de versiones compatibles | Elija un protocolo realmente compatible |
| Método desconocido | JSON-RPC -32601; una solicitud moderna puede devolver HTTP 404 | Compruebe la generación de protocolo y el método |
| Faltan parámetros o son inválidos | JSON-RPC: error de parámetros, o error de herramienta con isError | Corrija según el inputSchema real |
Elección de la herramienta y del canal de evidencia adecuados
Enrute según la pregunta de negocio aún sin resolver, en lugar de repetir la obtención de evidencia con una cadena de llamadas fija.
| Tarea | Herramienta preferida | Evidencia necesaria para darla por completada |
|---|---|---|
| Descubrir temas y recursos autorizados | dfc_ontologies dfc_ontology_resources | Tipos reales de ID de recursos y alcance visible actual |
| Estadísticas de tablas y TopN | dfc_table query | Recibo de ejecución correcta y evidenceRows completo |
| Consultar políticas, contratos o informes | dfc_ontology_query o knowledge search/detail | Texto original completo, autorizado y utilizable como hecho |
| Localizar objetos del grafo | dfc_ontology_graph search/neighbors | Localizar el origen real y, después, obtener el hecho correspondiente |
| Interacción original por palabras clave | dfc_manual y luego dfc_search | Resultados reales del modelo original y de los frames de negocio |
| Análisis integrado e informes | dfc_analysis_* o dfc_report_* | Estado real de cada rama estructurada y de la evidencia documental |
| Modificar la visualización o el modelo de ontología | dfc_authoring_* y herramientas de artifact | Verificar por separado candidatos, planes, aprobaciones y lo realmente aplicado |
| Ejecutar comandos de negocio | dfb_* de /mcp/business | Contratos publicados y recibo del ActionPlan original |
Evitar llamadas innecesarias
Cuando ya se dispone de la estructura de tablas actual, completa y autorizada, no es necesario volver a solicitar detail en cada consulta; cuando ya se dispone de una localización y evidencia fiables, no repita la misma búsqueda. Si falta una dimensión necesaria, realice una consulta complementaria acotada. Si un fallo claramente no admite reintentos, resuelva primero la carencia; no sustituya el criterio por «intentarlo de nuevo».
Exclusiones de Flash
Las capabilities de dfc_etl pueden devolver available=false y ETL_NOT_INCLUDED_IN_OT_FLASH. La documentación estática de las funciones ETL integradas sirve como referencia entre productos; no demuestra que Flash tenga instalado ETL, ni permite que el Agent pase automáticamente a ejecutarse en Heavy u otro tenant.
Recursos de ontología y tipos de ID
Obtenga primero las coordenadas reales de los recursos para no confundir nombres de almacenamiento, ID de documentos e ID de bases de conocimiento.
- Llame a dfc_ontologies y explore con page y pageSize las ontologías incluidas en esta autorización que sigan siendo legibles actualmente.
- Con un ontologyId real, llame a dfc_ontology_resources; seleccione tables, answers, pinboards, documents y knowledgeBindings según sea necesario.
- Gestione la paginación de cada tipo de recurso por separado. pageSize tiene un máximo de 100; no infiera el alcance completo del recurso a partir de la primera página.
- Guarde los tipos declarados de los recursos y sus ID originales, y utilícelos tal cual en las llamadas posteriores.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordenadas | Origen | No sustituye a |
|---|---|---|
| ontologyId | Lista de ontologías autorizadas o contexto vigente | ID de otra ontología |
| id del recurso de tabla | Lista de tables o contexto fiable | physicalName o nombre visible de la tabla |
| tblDisplayName colDisplayName | Metadatos actuales de tablas y columnas | Identificador físico SQL supuesto |
| knowledgeId | knowledgeBindings o recibo real de recuperación de conocimiento | id del recurso de documento |
| assetId documentId chunkId evidenceId | El mismo recibo real de localización | Campos ensamblados a partir de localizaciones distintas |
| rid revisionId releaseId | Modelo publicado o contexto de candidato del servidor | ID generado por el propio cliente o latest |
Convenciones de precisión
Todos los identificadores de recursos de 64 bits deben manejarse preferiblemente como cadenas decimales, sin pasar por Number en JavaScript. Algunos esquemas de negocio admiten string o integer, lo que no significa que se pueda descartar la precisión entera. Los opaque locator, UUID, hashes y tokens de un solo uso también deben conservarse tal cual.
Consulta de tablas Doris y contrato de estructura
Ejecute consultas SQL de solo lectura sobre tablas autorizadas, conservando la semántica de salida, los valores exactos y la integridad.
Lectura de la estructura
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}Use detail con un ID real de recurso de tabla. Compruebe schemaComplete, tblDisplayName, el colDisplayName de columns y el sqlDataType autoritativo, así como el queryContract devuelto. dataType es solo una asignación de compatibilidad; el nombre físico de almacenamiento no es el nombre de tabla que se envía en SQL.
Ejecución de consultas
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}Restricciones de SQL
- Utilice los nombres visibles de tablas y columnas, y delimite los identificadores entre comillas dobles. La solicitud es una consulta Doris de solo lectura dentro del ámbito de una ontología.
- Enumere explícitamente las columnas de salida; no se permiten SELECT * ni table.*, para que no se puedan eludir los permisos de las columnas registradas a través de columnas físicas.
- Las uniones usan JOIN ... ON explícito; NATURAL JOIN y JOIN USING se rechazan.
- Se permiten expresiones de solo lectura legítimas como agregaciones multidimensionales, CTE, ventanas, CASE, COUNT(DISTINCT ...); que la validación semántica no cubra una expresión no equivale a prohibir su ejecución de forma generalizada.
- Complete primero la agregación, la ordenación y el ranking en SQL y aplique después el límite de resultados. maxRows es 100 por defecto, con un máximo de 200.
Fechas y zonas horarias
| Tipo u objetivo | Forma | Nota |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) y CURRENT_DATE | No dé por hecho que un literal de texto sin conversión es de tipo fecha |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) y CURRENT_TIMESTAMP | Compruebe la zona horaria del origen y la de la sesión |
| Tiempo relativo | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Para fechas y marcas de tiempo, use la función de fecha u hora actual correspondiente |
| Agrupación temporal | YEAR(columna) o DATE_TRUNC(columna, 'month') | Asigne un alias único a cada salida; queryContract prevalece |
El DATE('now', ...) de SQLite no es el contrato de fechas Doris de este punto de entrada. No traslade a las consultas SQL en producción la verificación sin conexión con SQLite de los ejemplos de la documentación.
Lectura del recibo de consulta v8
evidenceRows es el único canal de datos de fila disponible para el Agent; los raw data no se exponen al Agent. Los números de SQL se codifican como cadenas decimales exactas en JSON; determine su valor numérico y tipo de negocio mediante resultColumnContracts, sin interpretarlos como VARCHAR solo porque en JSON sean cadenas. Lea executionReceipt, la información de integridad y de truncamiento, y conserve la información de origen como evidenceRowsSha256.
Las salidas de consulta con recibo de ejecución citable pueden citarse tal cual; solo la semántica verificada por el servidor autoriza cálculos secundarios deterministas posteriores. No adivine «saldo acumulado», «valor de cierre», «moneda» ni unidades a partir de los nombres de campo. Los resultados de cero filas, fallos o truncamientos no deben describirse como estadísticas completas.
Top3 multidimensional y manejo de truncamiento
Responda a las preguntas de clasificación mediante agregación y funciones de ventana en el servidor; no realice cálculos secundarios sobre resultados incompletos.
El archivo examples/top3.sql incluido usa la tabla de ejemplo: primero agrega por 区域, 类别 y 产品, luego ejecuta ROW_NUMBER dentro de cada 区域 y 类别, y usa el nombre de 产品 como orden estable en caso de empate en los importes. Solicitar maxRows=100 es suficiente para las 36 filas del ejemplo; otros datos de negocio requieren una evaluación según el número real de grupos.
- Obtenga la estructura real y la definición vigente, y aclare la moneda, el período, el estado del pedido (订单状态) y las reglas de desempate.
- Envíe una SQL que realice la agregación y la clasificación en el servidor. No consulte primero solo el total de 区域 para luego tratarlo como la clasificación de 产品 por 类别.
- Compruebe el contrato de columnas de salida y el evidenceRows real, y confirme que la respuesta cubre todos los grupos necesarios.
- Si detecta truncamiento, realice consultas por particiones acotadas según los límites admitidos por el servidor, por ejemplo obteniendo el Top3 completo por cada 区域; mantenga en cada paso la misma definición de negocio.
- Si el origen cambia entretanto, vuelva a consultar e identifique explícitamente la nueva versión; no mezcle versiones de datos distintas ni cursores caducados.
Recuperación de errores
TABLE_SCHEMA_INCOMPLETE: corrija la solicitud u obtenga la estructura completa; los fallos como ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID se gestionan según el errorCode, retryable y remediation devueltos. No afirme que «todos los GROUP BY multidimensionales o funciones de ventana están prohibidos» ni invente clasificaciones sin resultados de consulta.
Recuperación de conocimiento: texto original completo y elegibilidad de la evidencia
Separe la localización, la lectura y la cita de hechos, y conserve la procedencia y la integridad.
Dos rutas habituales
| Ruta | Propósito | Puntos clave |
|---|---|---|
| dfc_ontology_query | Buscar dentro del conocimiento vinculado a la ontología, pudiendo combinarse con enrutamiento por grafo | Comprobar el answerContextItems canónico completo y la elegibilidad de la evidencia |
| dfc_knowledge_search → chunk de dfc_knowledge_detail | Localizar mediante búsqueda explícita y luego leer el fragmento seleccionado | La vista previa de búsqueda no constituye un hecho; leer el texto original completo de la misma localización |
{"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>"
}}Condiciones para poder usarlo como hecho
- Compruebe la ACL actual, la integridad del contenido y el canonicalFactEligible, citationEligible del servidor o el contrato de ejecución correspondiente.
- Contenido completo vinculado a contentSha256. Los truncamientos, omisiones por presupuesto o contenidos de baja calidad se tratan según los campos reales.
- Los metadatos del documento, page_context, la localización por grafo, los resúmenes de recuperación y las vistas previas no sustituyen al texto canónico original.
- Copie preferentemente evidenceId; cuando necesite chunkId y documentId, deben provenir del mismo resultado de localización, sin combinarlos ni inventarlos.
Enrutamiento por grafo
El resultado de search/neighbors es información de localización. Pase a la query de la ontología únicamente el objeto routeLocator devuelto íntegramente por el servidor, incluidos los campos de vinculación, versión y prueba. No empaquete por su cuenta un assetId o knowledgeId como locator emitido por el servidor, ni devuelva pruebas de procedencia afirmadas por el modelo.
Recuperación de documentos estructurados
El structuredPlan de dfc_ontology_query es una recuperación restringida y verificación determinista diseñada específicamente para tablas de documentos irregulares. Úselo solo después de que se devuelvan el executionContractSha256 y tableIndex actuales, las columnas y la tabla completa, y siga el plan declarado por el servidor. Las tablas de negocio ya importadas deben usar dfc_table SQL; no utilice la recuperación de tablas Markdown como vía para eludir la autorización de consultas de tablas.
Estrategia de recuperación
knowledgeIds normalmente se omite para cubrir los vínculos habilitados actualmente; si se indica, use únicamente los ID reales de base de conocimiento de knowledgeBindings. No use el ID de un recurso de documento como ID de base de conocimiento. Realice nuevas búsquedas acotadas para preguntas no resueltas y evite recuperaciones exactamente repetidas que no aporten evidencia nueva.
Modelos y sesiones nativos de Search
Use el protocolo de palabras clave de Rust Search mediante dfc_search y espere el estado final de los frames de negocio originales.
Lea primero las instrucciones y luego descubra las capacidades
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search requiere un search:operate explícito. Envuelve el WebSocket original de palabras clave y no reescribe las palabras clave como solicitudes SQL ni de LLM. La sesión se vincula al tenant, usuario, Grant, cliente y modelo actuales, y en cada operación vuelve a comprobar los permisos originales de tabla y columna.
Flujo mínimo de sesión
{"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 recibe entre 1 y 100 ID reales de tablas sobre las que tenga permiso; como alternativa, model_read lee un sourceToken que ya posea.
- open solo devuelve initializationSent; haga poll primero, lea la respuesta de negocio init original y confirme el éxito.
- Lea assist y las sugerencias y, a continuación, envíe un message original admitido. En query datas, el wrapper fija isNl en false.
- Siga leyendo frames, distinguiendo sugerencias, interpretación, recepción y resultado de negocio final.
- Al terminar, cierre con close; si necesita cancelar, use cancel y verifique la finalización según el estado real de la tarea.
| action | data | Significado |
|---|---|---|
| capabilities | Omitido u objeto vacío | Leer acciones, comandos, TTL y notas de transporte |
| model_create | Matriz tableIds | Crear el modelo autorizado del usuario actual |
| model_read | sourceToken | Leer el modelo, filtrando columnas sin permiso y configuraciones de fuentes sensibles |
| open | sourceToken y language opcional | Establecer la sesión nativa y enviar init |
| request | sessionId y message | Enviar un mensaje del protocolo original type/datas |
| poll | sessionId y waitMillis entre 0 y 30000 | Recuperar los frames actuales del búfer con espera acotada opcional |
| cancel close | sessionId | Cerrar esta sesión nativa; no permite afirmar un estado final de BI |
Comandos originales admitidos
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteLas mayúsculas/minúsculas de los comandos y la estructura de datas siguen las capabilities actuales y el protocolo de la sesión original. No añada acciones inexistentes al request; por ejemplo, la grafía de disambiguite debe conservarse tal como aparece en el protocolo real. El tamaño máximo del mensaje es de 256 Ki caracteres.
Sesión e integridad
El TTL de la sesión es de 10 minutos y solo se conserva durante la vida del proceso actual; no es una tarea recuperable de forma persistente. El búfer admite como máximo 256 frames y está sujeto a límites de memoria; cuando bufferOverflow=true, no trate los frames ya recuperados como un resultado completo. Tras un error de transporte, haga poll primero en la sesión original; no reenvíe a ciegas consultas que puedan haberse ejecutado ya.
El wrapper actual no ofrece guardado de respuestas ni de pinboards, lectura y escritura del historial, ni restauración arbitraria de contexto. La existencia de exportContext no implica que se pueda restaurar cualquier contexto por cuenta propia. Para guardar resultados, use las capacidades de recursos originales realmente expuestas por la instancia; no invente actions.
Convenciones de idioma y región
Mantenga los límites entre la configuración regional de la interfaz, el diccionario de consultas, el idioma de respuesta y los nombres de campo originales.
La prioridad es: idioma solicitado explícitamente, idioma del sistema de la aplicación y locale del nodo de ejecución real. Un valor omitido, null, una cadena vacía o espacios en blanco no hacen que se recurra siempre al chino. El valor de región en languageRegistry debe mantenerse exacto; no reduzca arbitrariamente en-GB, fr-CA, pt-BR, es-US o ar-AE a otra variante regional.
| Idioma o región | Locale de consulta | Descripción |
|---|---|---|
| Chino simplificado, chino tradicional | zh-CN zh-Hant | Las reglas originales del chino difieren del catálogo de chino tradicional |
| Inglés de EE. UU., Reino Unido, Australia y Canadá | en-US en-GB en-AU en-CA | Los paquetes de interfaz/palabras clave pueden compartirse; los metadatos de región se conservan |
| Alemán, italiano, ruso | de-DE it-IT ru-RU | Usar según las sugerencias de la sesión actual |
| Español de España y de Latinoamérica | es-ES es-US | El ID de región del producto es es-US |
| Francés de Francia y Canadá | fr-FR fr-CA | Los ID de región no se fusionan |
| Portugués de Portugal y de Brasil | pt-PT pt-BR | El catálogo y las convenciones de región se conservan por separado |
| Neerlandés, danés, noruego, finlandés y sueco | nl-NL da-DK nb-NO fi-FI sv-SE | El noruego es Bokmål |
| Japonés, coreano | ja-JP ko-KR | No segmentar las palabras con reglas propias basadas en los espacios del inglés |
| Árabe de Arabia Saudí y de los Emiratos | ar-SA ar-AE | La ayuda de la interfaz admite RTL; los identificadores del protocolo no se invierten |
Uso del catálogo de palabras clave
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}El catálogo estático de palabras clave de dfc_manual solo incluye las configuraciones regionales enumeradas explícitamente; si se omite, se usa la referencia en inglés. Es un valor predeterminado de referencia, no una regla de análisis del idioma de consulta. Cuando no se ofrezca un catálogo estático para una variante regional, obtenga las sugerencias reales mediante assist de la sesión actual; no fabrique alias ni resultados de reserva. Cada llamada admite como máximo 32 elementos en names.
Contenido que no se traduce
- Tablas, columnas, valores de enumeración, nombres de clientes, nombres de fórmulas y demás cadenas reales del modelo.
- Nombres de herramientas, action, scope, campos de Schema, códigos de error y valores de estado.
- ID de recursos, hashes, opaque locators y referencias emitidas por el servidor.
Por ejemplo, una pregunta en alemán puede consultar la columna mostrada en chino «销售金额». Cambiarla por un nombre de columna en alemán crearía otro identificador, no una traducción de interfaz. Tras cambiar de idioma, reinicialice o actualice la sesión según el protocolo original, y vuelva a obtener sugerencias y candidatos de desambiguación.
Análisis integrado y resultados interactivos
En las herramientas de análisis disponibles de forma condicional, conserve la autorización, la versión, las ramas y el estado de la evidencia.
dfc_analysis_* se controla mediante datafocus.mcp.analysis.tools.enabled. La parte estructurada sigue usando consultas autoritativas de Search y la política de filas actual; la parte documental vuelve a obtener el texto original completo bajo la ACL actual. No son puntos de entrada abiertos para SQL, instrucciones arbitrarias ni inyección de filtros arbitrarios.
| Herramienta | Propósito | Coordenadas necesarias |
|---|---|---|
| dfc_analysis_ask | Formular una pregunta de análisis en lenguaje natural | ontologyId y question; opcionales: language y sessionId |
| dfc_analysis_result_get | Leer un resultado ya devuelto | ontologyId sessionId resultId |
| dfc_analysis_refine | Hacer preguntas de seguimiento o cambios sobre el resultado completo más reciente | expectedRevision del resultado original y clave de idempotencia estable |
| dfc_analysis_page | Obtener una página de una rama del servidor | pageNo pageSize de rama y versión de resultado originales |
| dfc_analysis_cancel | Cancelar un resultado aún en curso | Sesión y resultado originales |
| dfc_analysis_close | Liberar una sesión en estado no activo | Sesión original |
Iniciar el análisis
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Lea el sessionId, resultId, el estado y la revision devueltos; si es necesario, siga leyendo el resultado original.
- Compruebe uno a uno el estado, la integridad, la política de filas y el origen de cada rama estructurada; que una rama esté completa no implica que todo el análisis lo esté.
- Compruebe la evidencia documental, el registro de hechos, la elegibilidad de las citas y las limitaciones. Las narrativas generadas por el modelo no pueden elevar por sí solas la elegibilidad de la evidencia.
- Si necesita hacer preguntas de seguimiento, hágalo sobre el resultado completo más reciente y pase expectedRevision; al reintentar el mismo cambio, reutilice la misma clave de idempotencia.
- Antes de cerrar, confirme que la sesión ya no está en curso; cancelar y cerrar son acciones distintas.
Filtrado y paginación controlados
filter_patch usa los valores branchId, fieldRef, valueRef y los operadores permitidos que entrega el servidor; el filtrado tipado actual solo declara EQ. Está prohibido reemplazar las referencias opacas por SQL en bruto, tableId, columnId o un árbol de filtros fabricado por el cliente. La paginación pageNo comienza en 1, con un máximo de 10000; pageSize tiene un máximo de 100.
Indicaciones de capacidad y comportamiento
Las annotations de las herramientas son sugerencias para el cliente, no autorizaciones de seguridad. Algunas plantillas genéricas usan readOnlyHint y no sustituyen el juicio sobre la acción real; cancelar, cerrar y crear informes modifican el estado de trabajo correspondiente. Ejecute siempre según la semántica de la herramienta, el objetivo del usuario y los permisos del servidor.
Informes visualizables persistentes y MCP Apps
Cree informes reanudables y lea sus resultados e interfaz interactiva según los permisos actuales.
dfc_report_* está controlado por datafocus.mcp.analysis.report-tools.enabled y requiere los scope metadata y table query. A diferencia de las sesiones de Search que viven dentro del proceso, los informes usan un reportId persistente; que sea persistente no significa que se dejen de verificar los permisos.
{"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>"
}}Flujo de trabajo
- Al crear, use un idempotencyKey estable de entre 8 y 128 caracteres admitidos.
- Guarde el reportId, consulte periódicamente el status y compruebe el estado real: completado, fallido, parcialmente completado o cancelado.
- Al leer los resultados, verifique las ramas estructuradas, las visualizaciones, las fuentes de los hechos, las referencias documentales y la integridad.
- Para cancelar un informe sin completar, use el reportId original; no cree otro informe en lugar de cancelar.
- Si se agota el tiempo de espera de red, lea primero el estado del informe original; la repetición con la misma clave de idempotencia debe mantener la misma intención de negocio.
MCP Apps
Los clientes compatibles con extensiones de UI leen las páginas de informe mediante el _meta de la herramienta y el descubrimiento real de recursos. La página de informe persistente correspondiente a r56 es ui://datafocus/analysis-report/v16/index.html, y el análisis interactivo utiliza las referencias a recursos del servidor correspondientes; el cliente no debe codificar de forma fija valores que sustituyan a los devueltos por la herramienta. Sin extensiones de UI, los resultados estructurados siguen siendo legibles.
Vinculación de origen
La lectura del informe vuelve a verificar el Grant, la ontología, la vinculación del Origin de la solicitud y los permisos actuales de tabla. La integración entre orígenes en el navegador debe usar orígenes reales aprobados; el cliente no elude la vinculación falsificando el Origin. Un reportId antiguo no es un enlace público permanente ni una credencial de acceso entre usuarios.
Borradores de artefactos: vista previa, plan y aplicación
Entregue el contenido generado al servidor original para su normalización, validación y aprobación; no permita que el modelo modifique directamente los recursos de producción.
Las herramientas de artefactos requieren que la función authoring esté activada, el artifact type real, los scope pertinentes y los permisos de escritura de administrador originales. La configuración por defecto de tipos es CONTROL_PANEL_SPEC y VIEW_SPEC; los demás tipos (formularios, orígenes HTTP o scripts) dependen además de configuraciones independientes. Flash no tiene AutoML, por lo que los tipos relacionados no se enumeran como artefactos disponibles en esta versión.
- dfc_authoring_capabilities lee los contratos y acciones disponibles para el Grant actual.
- dfc_artifact_context obtiene el contexto acotado, contractVersion, contextHash, baseArtifactHash y baseArtifactVersion.
- Genere los candidatos en el cliente conforme a los contratos reales, sin ejecutar el código que contengan.
- dfc_artifact_submit envía el contexto original y el candidato, mantiene la instruction idéntica y usa un clientRequestId estable.
- Lea el proposalId, el candidateHash, la validación y la vista previa; si hay errores reales, revise el candidato y no simule que el servidor lo ha dado por válido.
- Cuando se requiera una nueva vista previa, use dfc_artifact_preview con el mismo hash de candidato.
- dfc_artifact_plan crea un plan inmutable con el candidato real, la versión de destino y la clave de idempotencia.
- Gestione la aprobación mediante la interacción de aprobación original o una política autorizada y, a continuación, llame a dfc_artifact_apply; solo el recibo APPLIED representa la aplicación efectiva.
Solicitud de contexto mínimo
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}VIEW_SPEC usa el projectId autorizado actualmente; al editar un artefacto existente, use el artifactId real. Los campos variables, previewInput, viewport, etc., se proporcionan según el contrato devuelto, sin inventar la estructura interna de los candidatos.
Concurrencia y reintentos
El plan queda vinculado a la versión de destino, al hash del candidato y a la clave de idempotencia. Si el destino cambia, el plan antiguo no puede seguir aplicándose; vuelva a leer el contexto y gestione el conflicto real. Un transport timeout no prueba el fallo; consulte primero con dfc_artifact_status el proposalId o planId original. READY no es APPLIED.
Aprobación y políticas automáticas
Los planes de artefactos genéricos requieren la aprobación humana del flujo original. Los planes que cumplan la política de publicación automática de la ontología se procesan según approvalMode y no exigen al usuario firmar otra aprobación inventada por el Agent. approvalToken es material emitido por el servidor y no puede sustituirse por una cadena escrita por el Agent; el inputSchema real y el recibo del plan determinan los campos obligatorios.
Contrato de creación y publicación de candidatos de ontología
Use declaraciones de ontología y configuraciones de publicación con versiones independientes; no aplique a la publicación de modelos el contrato de artefactos de simple visualización.
Creación de candidatos
El contenedor de ontología debe existir previamente y estar dentro del Grant. Use dfc_ontology_table_schema para comprobar los campos de origen estructurado actuales y la huella de Binding v4; los campos pueden proporcionarse solo con sourceField para el descubrimiento automático de tipos. Las declaraciones explícitas DECIMAL requieren la precisión y la escala actuales; los demás tipos no llevan estos dos campos.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Candidatos y configuración de publicación
| Contrato | Propósito | Límites clave |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Creación de candidatos con declaraciones locales | Orígenes realmente autorizados; compilación en el servidor; no se aceptan pruebas de finalización |
| ontology-workspace-create-mcp-submit-v2 | Combinación de referencias locales y referencias exactas a versiones publicadas | Proporcionar el releaseSelections exacto y las dependencias de la clausura |
| ontology-publication-mcp-submit-v1 hasta v3 | Vincular un candidato existente a una solicitud de plan de publicación | Coordenadas explícitas; el servidor recupera el destino, el origen, la aprobación y la validación |
| ontology-publication-mcp-submit-v4 hasta v6 | Configuraciones relacionadas con la publicación automática activadas de forma independiente | Solo se usan cuando las capabilities y el schema real las declaran |
| ontology-initial-activation-retirement-submit-v1 | Operación controlada de retirada de la activación inicial | Plan independiente con nueva aprobación humana y alcance exacto |
Secuencia de publicación
- Obtenga el workspaceId, workspaceRevision, candidateHash del candidato actual, así como los orígenes reales.
- Elija la versión del contrato según las capacidades del servidor; envíe coordenadas como releases y selection, sin adjuntar campos que afirmen por su cuenta «aprobado» o «validado».
- Conserve el proposalId devuelto por submit y el idempotencyKey original. submit y MODEL_PLAN son fases distintas de una misma solicitud.
- Llame a dfc_artifact_plan con el candidato original, la versión de destino y la misma clave de idempotencia.
- PLANNING_INCOMPLETE solo indica que aún no se ha formado un plan válido; VALIDATION_UNSATISFIED indica que la validación actual aún presenta deficiencias y debe tratarse según nextAction.
- Si el plan se crea correctamente, continúe según HUMAN_REQUIRED o POLICY_AUTO con las capacidades originales de aprobación y publicación.
- Confirme el resultado mediante el recibo APPLIED y la posterior lectura real del modelo publicado y consultas autorizadas.
Tiempos de espera y recuperación
Tras agotarse el tiempo de espera de PLAN, lea el proposalId original. MODEL_PLAN_SUBMITTED es una solicitud sin completar; MODEL_PLAN_COMPLETED indica que se debe recuperar el recibo original con las coordenadas y la clave originales, no que el cliente deba crear una nueva solicitud. Las deficiencias de validación en estado final no se convierten en una publicación aprobada cambiando la clave ni reenviando la solicitud.
Permisos humanos de negocio
La instruction y las declaraciones proporcionadas por el Agent son entradas del Agent, no firmas de políticas humanas. MODEL_AUTHOR, MODEL_PUBLISH, la delegación de publicación automática, la confirmación de negocio, la confianza de claves públicas, el presupuesto y las ACL de origen siguen dependiendo de los mecanismos originales. Ningún campo del cliente puede sustituir estos hechos.
Modelo publicado, consulta de candidatos y clausura de referencias
Use el conocimiento de negocio publicado por versiones exactas y conserve el carácter provisional de los candidatos no publicados.
En dfc_ontology_graph, published_model, published_query y candidate_query son configuraciones estructuradas disponibles de forma condicional, no sinónimos de un search/neighbors ordinario. Se autorizan mediante table query y los permisos de lectura de modelado necesarios; la visibilidad en el grafo no sustituye a los permisos de tabla.
Lectura del modelo publicado
- Cuando la enumeración action de la herramienta incluya realmente published_model, envíe el releaseId real ya confirmado (committed).
- v1 devuelve plantillas de consultas autorizadas; v2 añade referencias PERSISTED exactas y releaseSelections; v3 añade referencias de dependencias, domainRef exactos y plantillas de vinculación compactas.
- Seleccione objetos, propiedades, Binding, scope y versiones a partir de los valores realmente devueltos; no genere RIDs ni use latest.
- Envíe consultas tipadas fijas de published_query; los resultados deben superar igualmente la autorización vigente de origen y de campos.
Consulta de candidatos
candidate_query usa el workspaceId, la revision, el candidateHash y las declaraciones del candidato reales. Al combinar referencias publicadas, use las coordenadas tipadas LOCAL/PERSISTED de v2 correspondientes y selecciones exactas. Los resultados de candidatos son siempre no publicados y provisionales, y no deben tratarse como conocimiento confirmado por la empresa.
Mantenimiento parcial y clausura
Seleccione únicamente las dependencias transitivas necesarias para la raíz del candidato y garantice que cada referencia publicada tenga un releaseSelections exacto. Copiar el cuerpo publicado, enviar solo un conjunto de ID o ampliar a todos los recursos históricos no sustituye a la comprobación vigente de dependencias y orígenes.
La query de estas actions es un objeto tipado y versionado, y no acepta SQL, ID de tablas físicas ni nombres de tablas de origen en sustitución de sus referencias de negocio. Las plantillas de metadatos y los resultados del grafo, por sí mismos, no son citables como hechos.
Delegación de tareas al agente de ontología
Reanude el trabajo con tareas persistentes y el Grant original; no trate las instrucciones del Agent como aprobación humana.
dfc_ontology_agent solo se muestra cuando el Pi Runtime real y los permisos pertinentes están disponibles. QUERY usa capacidades de lectura; AUTHORING exige además un rol de modelado y el scope authoring correspondiente. No expone otro motor de ejecución sin restricciones.
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"start",
"ontologyId":"<ONTOLOGY_ID>","mode":"QUERY",
"instruction":"列出当前可查询的表,并说明各表用途",
"idempotencyKey":"retail-discovery-01"
}}
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"status",
"ontologyId":"<ONTOLOGY_ID>","runId":"<RUN_ID>"
}}Conjunto de parámetros estricto
start usa contractVersion, action, ontologyId, mode, instruction y idempotencyKey; status/cancel usan contractVersion, action, ontologyId y runId. El servidor comprueba el conjunto exacto de campos según la action. La instruction admite un máximo de 16000 caracteres; la clave tiene entre 1 y 128 caracteres admitidos y empieza por una letra o un número.
Reanudación y cancelación
- Conserve el runId, el Grant, el mode y la clave de idempotencia originales.
- La misma clave con la misma instruction reanuda el mismo run, sin reenviar otra tarea; si se cambia la instruction manteniendo la clave, la solicitud se rechaza.
- status consulta el estado de la tarea original. Tras completarse, aún deben verificarse sus consultas de tabla, evidencias o recibos de publicación.
- La cancelación usa el runId original; confirme el resultado con el estado real de la tarea.
La finalización de un run no es un recibo de publicación del modelo. La tarea de publicación se confirma mediante el estado del artifact original y las comprobaciones de origen; QUERY no otorga implícitamente permiso de escritura ni de publicación.
MCP del espacio de trabajo de negocio
Consulte registros según los contratos de negocio publicados y ejecute comandos mediante el ActionPlan original.
/mcp/business usa un protected resource independiente y la selección de sistemas de negocio; no puede reutilizar el Grant de la ontología en lugar de la autorización de negocio. El sistema de negocio debe estar publicado, disponible para ser invocado por el Agent, cumplir la política de seguridad original y el usuario actual debe tener realmente el rol y las capacidades de tiempo de ejecución necesarios.
| Scope | Herramienta | Límites |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Descubre solo los sistemas incluidos en esta autorización e invocables actualmente |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Registros legibles por el usuario actual y planes propios |
| business-system:plan | dfb_action_plan | Solo crea planes inmutables, sin ejecutarlos |
| business-system:execute | dfb_action_execute | Autorización explícita e independiente; ejecución según el riesgo y la aprobación |
- dfb_systems descubre los sistemas autorizados.
- dfb_system_describe lee el contrato publicado actual, el releaseId y todos los hashes, consultas y comandos.
- dfb_query usa el queryKey publicado y, cuando sea necesario, especifica objectKey, state, page y pageSize. No es SQL arbitrario.
- dfb_record y dfb_work_items leen los registros y los elementos pendientes actualmente permitidos.
- Antes de ejecutar, use dfb_action_plan para proporcionar el releaseId, el releaseHash, el canonicalIrHash, el agentManifestHash, el commandType, el planIdempotencyKey reales y el payload del contrato.
- Verifique riskClass, requiresApproval y status; cuando se afecten registros de destino, conserve expectedRecordVersion.
- dfb_action_execute ejecuta únicamente planes que pertenezcan a la conexión actual y estén listos; cuando se requiere aprobación humana, el token de aprobación lo emite DataFocus.
- Tras un fallo o un tiempo de espera agotado, use dfb_action_status para recuperar el plan original; los reintentos mantienen la semántica de idempotencia original.
Vinculación de conexión y versión
El plan queda vinculado al ID de aislamiento estable del Grant actual. Tras renovar el access token, pueden seguir procesándose los planes de la misma conexión; otra conexión OAuth no puede hacerse cargo de ellos. Durante la ejecución se vuelven a comprobar la versión publicada, los hashes de IR/manifest, la versión de los registros de destino, la caducidad del plan, la idempotencia y la aprobación. La allowlist OAuth no elude la gobernanza de negocio.
Entradas de conocimiento de negocio y preguntas pendientes de confirmación
Registre entradas de negocio cuando el procesador de producción correspondiente esté disponible, y conserve el límite de confirmación humana.
Las cuatro herramientas siguientes las añade de forma condicional el controlador MCP público según los procesadores instalados y el scope vigente. No aparecen siempre en el catálogo básico. La existencia del Schema declarado no implica que la instancia cuente con los procesadores, el presupuesto o los permisos necesarios; debe comprobarse primero tools/list.
| Herramienta | Propósito | Autorizaciones y efectos que no genera |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Registrar la entrada de negocio original para un espacio de trabajo existente | No genera preguntas de confirmación, no aprueba, no publica |
| dfc_ontology_knowledge_input_preview | Previsualizar temporalmente borradores de preguntas a partir de la entrada original | No persiste, no confirma, no produce recibos de producción |
| dfc_ontology_knowledge_question_submit | Guardar preguntas authored no confirmadas | No fusiona respuestas automáticamente, no obtiene permisos de responsable ni de publicación |
| dfc_ontology_business_scope_initialize | Inicializar explícitamente el alcance de consumidores de un sistema de negocio | No publica, no activa, no concede acceso al origen |
Entrada y vista previa
- Obtenga workspaceId, workspaceRevision, localRef y preparationDigest de la preparación real.
- propose registra las entradas de negocio con el contrato de input original y una idempotencyKey estable; la misma clave solo puede corresponder a la misma entrada.
- preview utiliza la clave de idempotencia de la entrada original y el ontologyId; cada vez devuelve la revisión del servidor y una ventana de 60 segundos; no es un recibo idempotente de finalización de producción.
- Cuando sea necesario almacenar la pregunta, question_submit utiliza una nueva clave de comando, la originalInputKey original, una questionRevision, validFrom, validUntil y expectedRevision explícitas; en la creación, expectedRevision es null.
Punto de entrada de confirmación humana
La knowledgeConfirmationPage devuelta por question_submit es solo una ruta relativa a la página original (que requiere iniciar sesión), con una pregunta precargada. No incluye Bearer, no abre la página automáticamente y no confirma el conocimiento. QUESTION_STORED_UNCONFIRMED indica claramente que aún no se ha confirmado, y no debe describirse en la respuesta como «conocimiento publicado».
Inicialización del alcance de consumidores
business scope initialize requiere a la vez el permiso de publicación de la ontología y ser el creador del sistema de negocio concreto o tener sobre él permiso de administración de SourceManager. Utiliza las coordenadas reales de domainRid, domainRevisionId y businessSystemId; el cliente no puede rellenar a su antojo consumerScope ni pruebas de finalización. Incluso con INITIALIZED y COMPLETED, la respuesta sigue indicando explícitamente published=false y activationAuthorized=false.
Estas solicitudes también se someten a una validación estricta de JSON, del conjunto de campos, del tamaño en bytes y de la profundidad. El límite de una solicitud de entrada es 1 MiB; algunas operaciones concretas tienen límites menores. Los esquemas completos de entrada y salida se entregan con la referencia de herramientas; no aplique la lógica permisiva de parámetros del wrapper MCP genérico a estos contratos estrictos.
Respuestas, errores y reintentos seguros
Interprete los errores por capas y mantenga las coordenadas de la tarea y la semántica de idempotencia.
| Capa | Contenido de la comprobación | Principio de tratamiento |
|---|---|---|
| Red y HTTP | Conexión TLS 401 403 400 404 405, etc. | No tratar una respuesta fallida como resultado normal de consulta |
| JSON-RPC | error.code message data | Distinguir problemas de protocolo, método, parámetros y autorización |
| Herramienta MCP | result.isError y structuredContent | Un HTTP 200 puede seguir conteniendo un fallo |
| Resultado de negocio | Estado real, integridad, motivo del fallo, nextAction | Recibido o listo no equivale a completado |
| Elegibilidad como hecho | executionReceipt citationEligible contentComplete | El contenido no elegible solo se usa para localizar o explicar carencias |
Casos frecuentes de HTTP
- 401: falta el Bearer o ya no es válido; renuévelo o vuelva a autorizar según el flujo actual de OAuth.
- 403: el Grant, el rol, el recurso seleccionado, los permisos de la fuente, el Origin o la configuración no se cumplen; no intente eludirlo repitiendo la solicitud.
- 400: el mensaje o el contrato versionado no es válido, incluidas inconsistencias entre cabeceras modernas y metadatos.
- 404: compruebe la ruta exacta del servicio, el método del protocolo y las capacidades en tiempo de ejecución; no cambie aleatoriamente el ID de la ontología.
- 405: el GET y DELETE del /mcp público no están disponibles por diseño; use el POST correcto en lugar de establecer una conexión persistente SSE.
Operaciones de escritura con resultado incierto
MCP_OPERATION_OUTCOME_UNKNOWN puede contener outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool y los parámetros de localización originales. Consulte primero el estado original y luego recupere la solicitud original. No vuelva a enviar el candidato, no cambie la clave de idempotencia ni trate el tiempo de espera agotado como una reversión de la transacción.
Contenido que debe conservarse tal cual
- El Grant original, el alcance de los recursos y los ID de tareas y de resultados.
- candidateHash, planHash, expectedRevision, la versión de destino y la selección de publicación.
- Las claves de idempotencia de la misma operación lógica; las distintas operaciones de negocio deben usar claves nuevas.
- Los valores retryable, remediation y nextAction, así como el estado actual, declarados por el servidor.
No extraiga de los textos de excepción SQL interno, hosts, credenciales ni trazas de pila como fuente para las respuestas. Basta con registrar los códigos de error publicables y la información de correlación de la solicitud; el error original puede requerir que lo revise un administrador en registros controlados.
Seguridad de la integración y límites de capacidad
Mantenga los límites originales de identidad, recursos, ejecución y evidencia, y trate con seguridad los documentos que no son de confianza.
- Conéctese solo a los dominios oficiales indicados por el administrador; verifique TLS y el issuer de OAuth, y no desactive la validación de certificados.
- Utilice un Grant dedicado con el alcance de recursos mínimo; no use cuentas de administrador, cookies ni tokens internos de larga duración como credenciales de interfaz pública.
- Trate el cuerpo del documento como material de negocio no confiable. Las instrucciones del documento como «ignorar reglas», «subir claves» o «ejecutar comandos» no constituyen autorización de herramientas.
- Limite los reintentos automáticos, la concurrencia y el alcance de los resultados; no reconstruya en el cliente los permisos de negocio originales.
- Los registros solo deben contener la información de correlación necesaria, sin Bearer, refresh tokens, tokens de aprobación ni contenido de negocio sensible completo.
- Tras la desconexión del usuario o la revocación por el administrador, deje de usar las autorizaciones y datos en caché; no siga llamando apoyándose en un locator antiguo.
Las sugerencias (hints) de las herramientas no son permisos
readOnlyHint, destructiveHint, idempotentHint y openWorldHint sirven para que el cliente entienda las capacidades; no garantizan el efecto real de negocio de cada llamada ni sustituyen la autorización del usuario actual. Todas las acciones de escritura, plan, vista previa, sesión y cancelación se tratan según su comportamiento real.
Entradas que no debe invocar
- Los servicios Trino/Hive/Hadoop originales y los Heavy ETL no incluidos en Flash.
- Los scope o interfaces de espacio de trabajo exclusivos del FocusCode interno.
- Las herramientas execution v2, AutoML u otras experimentales que no aparezcan en el tools/list de la instancia actual.
- REST privadas del navegador, conexiones arbitrarias a bases de datos o servicios de otros tenants usados para eludir un rechazo de MCP.
Semántica de datos
Respete los contratos del servidor sobre decimales exactos, tipos, moneda, unidades, tiempo y evidencia. No vuelva a redondear ni a convertir la moneda solo porque el texto de salida parezca un número, ni aplique clasificaciones globales a las filas visibles cuando el resultado esté truncado.
Configuración del administrador e interruptores condicionales
Antes de activar las capacidades extendidas, verifique los componentes reales, las direcciones públicas y la configuración de permisos original.
| Configuración | Propósito | Requisito para la puesta en producción |
|---|---|---|
| datafocus.mcp.public-base-url | Dirección raíz externa oficial | Coherencia entre el descubrimiento OAuth, el issuer, el callback y el proxy inverso |
| datafocus.mcp.allowed-origins | Orígenes de navegador aprobados adicionalmente | Configuración precisa, sin ampliar a orígenes arbitrarios |
| datafocus.mcp.oauth.route-proof-secret | Secreto de servidor dedicado a las pruebas de enrutamiento del grafo | Guardar por separado; no usar el Bearer como clave |
| datafocus.mcp.analysis.tools.enabled | Herramientas de análisis interactivo | Servicios de datos, conocimiento y permisos asociados realmente disponibles |
| datafocus.mcp.analysis.report-tools.enabled | Herramientas de informes persistentes | Almacenamiento asociado, worker y cadena de recuperación disponibles |
| datafocus.mcp.analysis.apps.enabled | Presentación de MCP Apps | El cliente declara compatibilidad y comprueba el _meta devuelto |
| datafocus.mcp.authoring.enabled | Contratos de borrador y modelado | Conservar los permisos originales de administrador y de recursos |
| datafocus.mcp.authoring.apply-enabled | Capacidad de aplicación de artefactos | Plan inmutable, aprobación original y reverificación del estado actual |
| datafocus.mcp.ontology-published-query-enabled | Modelos y consultas publicados | Versión realmente confirmada y autorización del origen |
| datafocus.mcp.ontology-candidate-query-enabled | Consulta estructurada de candidato | Propiedad del candidato, versión precisa y permiso de lectura |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Autorizaciones de delegación de publicación automática | Política original vigente, confianza de clave pública, presupuesto y permiso de publicación |
Estos nombres provienen de la configuración e implementación de r56; si pueden activarse depende de los servicios asociados y de los controles originales de puesta en producción. Cambiar solo los valores booleanos no completa los procesadores, bases de datos, presupuestos de validación o políticas que falten. La visibilidad de las extensiones de entrada de conocimiento y de las tareas Pi depende de los componentes realmente instalados.
Proxy perimetral
Conserve Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name y el Origin aprobado. Configure el cuerpo de la solicitud, los tiempos de espera y TLS según los requisitos reales del servicio; no reenvíe el /mcp público al puerto de administración ni a otro producto.
Lista de comprobación de puesta en producción
- El estado del descubrimiento anónimo y de las llamadas protegidas es el esperado.
- Los usuarios normales solo descubren su alcance autorizado; tras revocar los permisos, las solicitudes posteriores se rechazan.
- Las sesiones nativas de Search, SQL, los textos originales y los informes opcionales tienen cada uno resultados reales.
- La aprobación y la recuperación idempotente de escrituras y publicaciones mantienen el comportamiento original.
- Los registros y la documentación pública no contienen claves privadas, tokens, cookies, contraseñas ni datos internos de clientes.
Cliente ejecutable y ejemplos de llamada
Utilice el cliente mínimo asociado para validar los mensajes, sin eludir OAuth ni la autorización actual.
examples/flash_mcp.py es un cliente de protocolo mínimo que depende solo de la biblioteca estándar de Python. No inicia sesión, no aprueba en nombre del usuario ni invoca automáticamente herramientas no visibles; admite los protocolos moderno y antiguo y, al salir, distingue por capas los errores de HTTP, JSON-RPC y de herramienta. El token se proporciona mediante variables de entorno del proceso, sin escribirlo en scripts ni archivos de documentación.
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_TOKENLectura y consulta
python3 examples/flash_mcp.py call dfc_ontology_resources \
--arguments-file examples/requests/ontology-resources.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/table-detail.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/top3-query.jsonSustituya primero los marcadores de posición como ONTOLOGY_ID y TABLE_RESOURCE_ID del archivo de solicitud por los valores reales devueltos por la autorización actual. El cliente rechaza la ejecución si encuentra marcadores de posición. El ejemplo de SQL requiere que el CSV incluido se haya importado con los nombres de columna originales; no puede enviarse directamente si no existe el esquema correspondiente.
Otros escenarios
- Entrada de negocio: use --endpoint business para obtener de nuevo un Grant orientado a /mcp/business.
- Cliente antiguo: elija --protocol 2025-11-25, realice primero initialize y después invoque con el mismo protocolo.
- Documentación integrada: use resources o read-resource para leer el URI real.
- Autocomprobación sin conexión: --self-test valida la construcción de cabeceras y metadatos modernos, no necesita token ni envía solicitudes al servidor del producto.
Límites del ejemplo
El cliente es un punto de partida para integrarse con el protocolo; no genera automáticamente candidatos de modelado, no guarda preguntas y respuestas ni ejecuta publicaciones. Emite el JSON original para que el Agent de capa superior verifique el estado de negocio; no prometa al usuario la finalización de consultas, informes o publicaciones basándose solo en el código de salida del proceso.
Incrustación de la interfaz de diálogo de la ontología
Incruste la página de diálogo para personas en el frontend de negocio y mantenga los límites de seguridad del inicio de sesión y del navegador.
<iframe
title="OT Flash ontology agent"
src="https://flash.example.com/10001/#/embed/ontology-agent/1001"
style="width:100%;height:760px;border:0"
referrerpolicy="strict-origin-when-cross-origin">
</iframe>10001 es un ID de tenant de ejemplo y 1001 un ID de ontología de ejemplo; al usarlos, sustitúyalos por coordenadas reales con permiso. Una única ontología puede especificarse por path o por un query admitido; el modo all ofrece @ para seleccionar las ontologías accesibles al usuario actual. skillId solo se transmite tal cual; no afirme por ello que la orquestación de habilidades ya pueda ejecutarse.
Autenticación y dominio
La página incrustada depende del estado real de inicio de sesión de DataFocus y comprueba /uc/status. Las cookies entre sitios, SSO, los frame-ancestors de CSP y la configuración de la pasarela afectan a la incrustación. No acepta introducir un Bearer de MCP en la URL como vía para omitir el inicio de sesión; los enlaces externos outside no implementados no deben construirse a mano siguiendo sugerencias de diseño.
Diferencias entre MCP e iframe
| Modalidad | Usuario | Identidad y resultado |
|---|---|---|
| Remote MCP | Integración de un Agent o servicio externo | Grant de OAuth y recibos estructurados de herramientas |
| iframe de diálogo de ontología | Usuario final humano | Sesión iniciada original e interfaz de diálogo |
| MCP Apps | Cliente MCP compatible con extensiones | Recursos controlados y resultados actuales de herramientas; no sustituyen al inicio de sesión de un iframe público |
Lista de verificación de aceptación de la integración
Demuestre la cadena de negocio completa en una instancia real, en lugar de limitarse a confirmar que las interfaces devuelven 200.
- Descubrimiento: obtener las versiones compatibles reales, el catálogo actual de herramientas y los recursos integrados.
- Autorización: los usuarios normales solo ven las ontologías y los sistemas de negocio permitidos; las operaciones sin el scope necesario se rechazan.
- Estructura de tablas: nombres visibles, columnas, tipos y permisos reales completos.
- SQL: las comprobaciones de una sola dimensión, multidimensionales, JOIN, fechas, TopN y truncamiento se ajustan al criterio real del negocio.
- Conocimiento: la localización, el texto original completo y la elegibilidad de las citas de hechos son coherentes; las preguntas mixtas cuentan con fundamentos de datos y documentos.
- Search: las comprobaciones de modelo, init, sugerencias, resultados, cierre e integridad del búfer se superan.
- Análisis e informes opcionales: el estado real de varias ramas, paginación, cambios de permisos y cancelación conservan el comportamiento original.
- Modelado opcional: candidatos, planes, aprobación original, aplicación efectiva y consulta de versiones se verifican fase por fase.
- Acciones de negocio: verificación del hash de publicación, versión de destino, aprobación, idempotencia y aislamiento entre Grants.
- Recuperación: tras agotarse el tiempo de espera de red se recupera el estado original; tras una actualización de la fuente, las localizaciones antiguas dejan de ser válidas y se usa una nueva consulta.
Registro de resultados
Registre la versión de la instancia, el rol del usuario, el alcance del Grant, la versión de configuración, las operaciones reales y los resultados. Marque por separado la autocomprobación sin conexión del cliente de protocolo, los valores esperados sin conexión del CSV de ejemplo, la validación estática del esquema JSON y la verdadera aceptación funcional en línea. No extrapole la superación de una fase a la superación de todo el producto.
Recursos de especificación y mantenimiento
Utilice el esquema de herramientas completo que acompaña al manual y manténgalo sincronizado con los resultados reales de descubrimiento de la instancia.
| Recursos | Contenido |
|---|---|
| reference/mcp-tool-catalog.json | 32 esquemas de entrada declarados del lado de la ontología y 8 del lado del negocio; algunas herramientas incluyen el esquema de salida original |
| reference/locales.json | 21 opciones seleccionables, 24 locale compatibles y terminología de UI |
| reference/search-keywords.json | 17 catálogos estáticos de palabras clave con locale explícito |
| reference/analysis-contract-manifest.json | Restricciones de versión relacionadas con análisis, ramas, hechos, recibos e informes |
| examples/ | CSV sintético, explicación de criterios, SQL de Top3, resultados esperados y cliente de protocolo mínimo |
Recursos de documentación integrados
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/list y resources/read requieren que el usuario actual tenga al menos la aptitud de lectura correspondiente a uno de estos scope: metadata, search operate o etl operate. Los documentos ETL son una referencia estática entre productos; las capacidades ejecutables de Flash siguen limitándose al alcance que Flash informa explícitamente.
Referencias de protocolos externos
Para el protocolo MCP y los antecedentes de autorización, consulte las especificaciones oficiales: https://modelcontextprotocol.io/specification/2026-07-28/basic y https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. Los puntos de conexión, las herramientas y los comportamientos condicionales de este producto se rigen por la implementación de r56 y los resultados actuales de descubrimiento de la instancia; no se puede equiparar la compatibilidad general con el protocolo a que el servidor proporcione todas las funciones opcionales.
Mantenimiento de actualizaciones
Al actualizar, vuelva a descubrir herramientas y versiones, y compare los esquemas de entrada, los contratos de salida y la configuración; los Grants antiguos no obtienen automáticamente los nuevos scope. Mantenga las referencias, las cachés y los recibos vinculados a la versión de origen; tras confirmar cambios incompatibles, vuelva a obtener el contexto y no aplique localizaciones antiguas a nuevos estados de negocio.
Referencia de parámetros de herramientas: básicas y Search nativo
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfc_manual
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| names | array | Opcional u obligatorio condicional | Nombres explícitos que se deben buscar, máximo 32 por llamada. maxItems: 32 |
| action | string | Opcional u obligatorio condicional | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: list, read, keywords, functions, etl_requests |
| locale | string | Opcional u obligatorio condicional | Locale explícito del catálogo de referencia estático, no el idioma predeterminado de las consultas. |
| uri | string | Opcional u obligatorio condicional | URI de los recursos integrados listados por la herramienta actual. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| data | object | Opcional u obligatorio condicional | Carga útil de la acción original; consulte el descubrimiento de capacidades y la tabla de campos de acciones. |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| data | object | Opcional u obligatorio condicional | Carga útil de la acción original; consulte el descubrimiento de capacidades y la tabla de campos de acciones. |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: capabilities |
dfc_ontologies
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| pageSize | integer | Opcional u obligatorio condicional | Número de registros por página; según el límite superior del esquema. minimum: 1; maximum: 100 |
| page | integer | Opcional u obligatorio condicional | Número de página, comenzando en 1. minimum: 1 |
dfc_ontology_resources
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| resourceTypes | array | Opcional u obligatorio condicional | Conjunto de tipos de recursos que se deben devolver. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| pageSize | integer | Opcional u obligatorio condicional | Número de registros por página; según el límite superior del esquema. minimum: 1; maximum: 100 |
| page | integer | Opcional u obligatorio condicional | Número de página, comenzando en 1. minimum: 1 |
Referencia de parámetros de herramientas: tablas, grafo y conocimiento
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfc_ontology_graph
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| relationTypes | array | Opcional u obligatorio condicional | Filtro por tipo de relación. |
| depth | integer | Opcional u obligatorio condicional | Profundidad de recorrido de vecinos. minimum: 1; maximum: 3 |
| sourceTypes | array | Opcional u obligatorio condicional | Filtro por tipo de origen. |
| query | object | Opcional u obligatorio condicional | Texto de consulta, o el objeto de consulta versionado exacto correspondiente a action. |
| limit | integer | Opcional u obligatorio condicional | Límite de resultados devueltos. minimum: 1; maximum: 100 |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| nodeKey | string | Opcional u obligatorio condicional | Clave de nodo copiada de los resultados reales del grafo. |
| keyword | string | Opcional u obligatorio condicional | Palabra clave de localización en el grafo; no es la sintaxis de consultas por palabras clave. |
| nodeTypes | array | Opcional u obligatorio condicional | Filtro por tipo de nodo. |
dfc_ontology_query
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| routeLocators | array | Opcional u obligatorio condicional | Localizadores de ruta tipados emitidos por el servidor, copiados íntegramente. maxItems: 20 |
| topK | integer | Opcional u obligatorio condicional | Límite de candidatos recuperados; no garantiza una cobertura completa. minimum: 1; maximum: 20 |
| queryMode | string | Opcional u obligatorio condicional | Seleccione el modo de consulta de evidencias según la enumeración de la herramienta. enum: vector, hybrid, graph |
| fanoutPlan | object | Opcional u obligatorio condicional | Plan de recuperación de ramas restringido, según el esquema anidado. |
| structuredPlan | object | Opcional u obligatorio condicional | Plan vinculado al contrato del servidor para tablas de documentos completas; no es SQL. |
| knowledgeIds | array | Opcional u obligatorio condicional | ID de la base de conocimiento dentro del knowledgeBindings real. |
| query | string | Obligatorio | Texto de consulta, o el objeto de consulta versionado exacto correspondiente a action. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
dfc_knowledge_search
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| topK | integer | Opcional u obligatorio condicional | Límite de candidatos recuperados; no garantiza una cobertura completa. minimum: 1; maximum: 20 |
| minScore | number | Opcional u obligatorio condicional | Puntuación mínima de coincidencia. minimum: 0; maximum: 1 |
| knowledgeIds | array | Opcional u obligatorio condicional | ID de la base de conocimiento dentro del knowledgeBindings real. |
| query | string | Obligatorio | Texto de consulta, o el objeto de consulta versionado exacto correspondiente a action. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| assetIds | array | Opcional u obligatorio condicional | ID de activos documentales actualmente permitidos. |
| retrievalStrategy | string | Opcional u obligatorio condicional | Estrategia de recuperación realmente compatible. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| qdrantId | string / integer | Opcional u obligatorio condicional | Identificador de índice devuelto por la localización real. |
| pageNo | integer | Opcional u obligatorio condicional | Número de página real o de la paginación. |
| evidenceId | string | Opcional u obligatorio condicional | ID de evidencia devuelto por la misma localización de conocimiento. |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: chunk, document, page_context |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| documentId | string / integer | Opcional u obligatorio condicional | ID del documento de la misma localización. |
| radius | integer | Opcional u obligatorio condicional | Rango de páginas adyacentes. minimum: 0; maximum: 3 |
| chunkId | string | Opcional u obligatorio condicional | ID real del fragmento de la misma localización. |
dfc_table
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| maxRows | integer | Opcional u obligatorio condicional | Límite de filas devueltas; no es un rango de clasificación del cliente. minimum: 1; maximum: 200 |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: detail, query |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| id | string | Opcional u obligatorio condicional | ID real del recurso de tabla, no el nombre físico ni el nombre visible. |
| sql | string | Opcional u obligatorio condicional | Doris SQL de solo lectura dentro del alcance de una única ontología, con columnas de salida explícitas. |
Referencia de parámetros de herramientas: análisis e informes
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfc_analysis_ask
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| question | string | Obligatorio | Pregunta en lenguaje natural o pregunta de seguimiento compatible. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| language | string | Opcional u obligatorio condicional | Locale explícito de respuesta o consulta; si se omite, se aplican las reglas de la herramienta correspondiente. |
| sessionId | string | Opcional u obligatorio condicional | Localización real de la sesión bajo el mismo Grant. |
dfc_analysis_refine
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| branchId | string | Opcional u obligatorio condicional | Localización de rama estructurada emitida por el servidor. |
| resultId | string | Obligatorio | Localización de los resultados de análisis devueltos originalmente. |
| question | string | Opcional u obligatorio condicional | Pregunta en lenguaje natural o pregunta de seguimiento compatible. |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| change | object | Opcional u obligatorio condicional | Cambio en lenguaje natural o filter_patch tipado. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| language | string | Opcional u obligatorio condicional | Locale explícito de respuesta o consulta; si se omite, se aplican las reglas de la herramienta correspondiente. |
| sessionId | string | Obligatorio | Localización real de la sesión bajo el mismo Grant. |
| expectedRevision | integer | Obligatorio | Precondición de versión del resultado original o de la cabecera de negocio; puede ser null al crear una pregunta. minimum: 1 |
| visualId | string | Opcional u obligatorio condicional | Localización de visualización vinculada a la rama. |
dfc_analysis_page
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| branchId | string | Obligatorio | Localización de rama estructurada emitida por el servidor. |
| resultId | string | Obligatorio | Localización de los resultados de análisis devueltos originalmente. |
| pageNo | integer | Obligatorio | Número de página real o de la paginación. minimum: 1; maximum: 10000 |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| pageSize | integer | Obligatorio | Número de registros por página; según el límite superior del esquema. minimum: 1; maximum: 100 |
| sessionId | string | Obligatorio | Localización real de la sesión bajo el mismo Grant. |
| expectedRevision | integer | Obligatorio | Precondición de versión del resultado original o de la cabecera de negocio; puede ser null al crear una pregunta. minimum: 1 |
dfc_analysis_result_get
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| resultId | string | Obligatorio | Localización de los resultados de análisis devueltos originalmente. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| sessionId | string | Obligatorio | Localización real de la sesión bajo el mismo Grant. |
dfc_analysis_cancel
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| resultId | string | Obligatorio | Localización de los resultados de análisis devueltos originalmente. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| sessionId | string | Obligatorio | Localización real de la sesión bajo el mismo Grant. |
dfc_analysis_close
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| sessionId | string | Obligatorio | Localización real de la sesión bajo el mismo Grant. |
dfc_report_create
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| goal | string | Obligatorio | Objetivo del análisis del informe. |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| language | string | Opcional u obligatorio condicional | Locale explícito de respuesta o consulta; si se omite, se aplican las reglas de la herramienta correspondiente. |
| title | string | Opcional u obligatorio condicional | Título opcional del informe. |
dfc_report_status
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| reportId | string | Obligatorio | Localización del informe persistente del Grant actual. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
dfc_report_cancel
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| reportId | string | Obligatorio | Localización del informe persistente del Grant actual. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
Referencia de parámetros de herramientas: modelado y tareas originales
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfc_ontology_agent
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| mode | string | Opcional u obligatorio condicional | QUERY o AUTHORING, con capacidades autorizadas por separado. enum: QUERY, AUTHORING |
| instruction | string | Opcional u obligatorio condicional | Texto de los requisitos del usuario; el contexto debe ser coherente con el envío. maxLength: 16000 |
| idempotencyKey | string | Opcional u obligatorio condicional | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. maxLength: 128 |
| action | string | Obligatorio | Nombre de la operación. Úselo según la enumeración actual y los parámetros correspondientes a la acción. enum: start, status, cancel |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| runId | string | Opcional u obligatorio condicional | ID de la tarea original de la misma ontología y el mismo Grant. |
| contractVersion | string | Obligatorio | Debe usarse la versión exacta del contrato realmente admitida. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
El objeto raíz de entrada de esta herramienta no tiene campos; use un objeto arguments vacío.
dfc_artifact_context
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Opcional u obligatorio condicional | Tipo de alcance de recursos del contrato real del artefacto. |
| ontologyId | string | Opcional u obligatorio condicional | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| projectId | string | Opcional u obligatorio condicional | ID del proyecto de la autorización actual. |
| artifactId | string | Opcional u obligatorio condicional | ID real del artefacto existente que se va a editar. |
| instruction | string | Obligatorio | Texto de los requisitos del usuario; el contexto debe ser coherente con el envío. |
| variables | object | Opcional u obligatorio condicional | Objeto de variables proporcionado según el contrato devuelto. |
| previewInput | object | Opcional u obligatorio condicional | Entrada de vista previa acotada proporcionada según el contrato. |
| viewport | object | Opcional u obligatorio condicional | Viewport de visualización requerido por el contrato original. |
dfc_ontology_table_schema
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| sourceAssetRef | string | Obligatorio | Referencia estructurada de activo registrada, por ejemplo table:123. |
| fields | array | Obligatorio | Declaración de campos de la fuente actual y tipos explícitos opcionales. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| proposalId | string | Obligatorio | ID del candidato original creado bajo el Grant actual. |
| candidateHash | string | Obligatorio | Hash exacto del candidato original del servidor. |
| previewInput | object | Obligatorio | Entrada de vista previa acotada proporcionada según el contrato. |
dfc_artifact_status
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| proposalId | string | Opcional u obligatorio condicional | ID del candidato original creado bajo el Grant actual. |
| planId | string | Opcional u obligatorio condicional | ID del plan de aplicación inmutable. |
dfc_artifact_plan
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| proposalId | string | Obligatorio | ID del candidato original creado bajo el Grant actual. |
| candidateHash | string | Obligatorio | Hash exacto del candidato original del servidor. |
| expectedTargetVersion | integer | Obligatorio | Precondición de la versión de destino real actual. minimum: 0 |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
dfc_artifact_apply
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| planId | string | Obligatorio | ID del plan de aplicación inmutable. |
| planHash | string | Obligatorio | Hash devuelto por el plan original. |
| approvalToken | string | Obligatorio | Material de aprobación emitido por el servidor original; está prohibido generarlo por cuenta propia. |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
dfc_artifact_submit
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| Configuración 1 / artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Configuración 1 / scopeType | string | Opcional u obligatorio condicional | Tipo de alcance de recursos del contrato real del artefacto. |
| Configuración 1 / ontologyId | string | Opcional u obligatorio condicional | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| Configuración 1 / projectId | string | Opcional u obligatorio condicional | ID del proyecto de la autorización actual. |
| Configuración 1 / artifactId | string | Opcional u obligatorio condicional | ID real del artefacto existente que se va a editar. |
| Configuración 1 / instruction | string | Obligatorio | Texto de los requisitos del usuario; el contexto debe ser coherente con el envío. |
| Configuración 1 / variables | object | Opcional u obligatorio condicional | Objeto de variables proporcionado según el contrato devuelto. |
| Configuración 1 / previewInput | object | Opcional u obligatorio condicional | Entrada de vista previa acotada proporcionada según el contrato. |
| Configuración 1 / viewport | object | Opcional u obligatorio condicional | Viewport de visualización requerido por el contrato original. |
| Configuración 1 / contractVersion | string | Obligatorio | Debe utilizarse la versión exacta del contrato realmente admitida. |
| Configuración 1 / contextHash | string | Obligatorio | Hash del contexto completo devuelto por context. |
| Configuración 1 / baseArtifactHash | string | Obligatorio | Hash del artefacto base devuelto por context. |
| Configuración 1 / baseArtifactVersion | integer | Obligatorio | Versión base devuelta por context. minimum: 0 |
| Configuración 1 / candidate | object | Obligatorio | Candidato conforme al contrato devuelto actual. |
| Configuración 1 / clientRequestId | string | Obligatorio | Clave de idempotencia del cliente utilizada de forma estable para la solicitud de candidato actual. |
| Configuración 2 / artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: ONTOLOGY_RELEASE |
| Configuración 2 / contractVersion | string | Obligatorio | Debe utilizarse la versión exacta del contrato realmente admitida. 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 |
| Configuración 2 / ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| Configuración 2 / candidateHash | string | Obligatorio | Hash exacto del candidato original del servidor. |
| Configuración 2 / workspaceId | string | Obligatorio | Coordenadas reales del espacio de trabajo del candidato. |
| Configuración 2 / workspaceRevision | string | Obligatorio | Versión exacta del candidato; no usar latest. |
| Configuración 2 / releases | object | Obligatorio | Selección de la versión exacta según el contrato de publicación de la ontología. |
| Configuración 2 / selection | object | Obligatorio | Proporciona solo coordenadas explícitas de selección de negocio; no proporciona permisos ni pruebas de finalización. |
| Configuración 2 / idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| Configuración 3 / Configuración 1 / artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: ONTOLOGY_RELEASE |
| Configuración 3 / Configuración 1 / contractVersion | string | Obligatorio | Debe utilizarse la versión exacta del contrato realmente admitida. enum: ontology-workspace-create-mcp-submit-v1 |
| Configuración 3 / Configuración 1 / ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| Configuración 3 / Configuración 1 / workspaceId | string | Obligatorio | Coordenadas reales del espacio de trabajo del candidato. |
| Configuración 3 / Configuración 1 / resources | array | Obligatorio | Declaración del modelo fuente compilada por el servidor. minItems: 1 |
| Configuración 3 / Configuración 1 / idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| Configuración 3 / Configuración 2 / artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: ONTOLOGY_RELEASE |
| Configuración 3 / Configuración 2 / contractVersion | string | Obligatorio | Debe utilizarse la versión exacta del contrato realmente admitida. enum: ontology-workspace-create-mcp-submit-v2 |
| Configuración 3 / Configuración 2 / ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| Configuración 3 / Configuración 2 / workspaceId | string | Obligatorio | Coordenadas reales del espacio de trabajo del candidato. |
| Configuración 3 / Configuración 2 / resources | array | Obligatorio | Declaración del modelo fuente compilada por el servidor. minItems: 1 |
| Configuración 3 / Configuración 2 / idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| Configuración 3 / Configuración 2 / releaseSelections | object | Obligatorio | releaseId exacto de cada referencia publicada y su clausura de dependencias. |
| Configuración 4 / artifactType | string | Obligatorio | Tipo de artefacto o de publicación de ontología realmente habilitado. enum: ONTOLOGY_RELEASE |
| Configuración 4 / contractVersion | string | Obligatorio | Debe utilizarse la versión exacta del contrato realmente admitida. enum: ontology-initial-activation-retirement-submit-v1 |
| Configuración 4 / ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| Configuración 4 / domainRid | string | Obligatorio | RID real del dominio de negocio. |
| Configuración 4 / consumerScopes | array | Obligatorio | Alcance exacto de consumidores permitido por el servidor. minItems: 1; maxItems: 256 |
| Configuración 4 / idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
Referencia de parámetros de herramientas: entrada de conocimiento y alcance
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfc_ontology_knowledge_input_propose
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| request | object | Obligatorio | Solicitud de entrada de negocio original; según el esquema anidado completo. |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. minLength: 1; maxLength: 128 |
Esta herramienta cuenta además con un outputSchema nativo. Compruebe la integridad del resultado, el estado y los campos de autorización marcados explícitamente como false; no amplíe por su cuenta el significado de «completado».
dfc_ontology_knowledge_input_preview
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. minLength: 1; maxLength: 128 |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
Esta herramienta cuenta además con un outputSchema nativo. Compruebe la integridad del resultado, el estado y los campos de autorización marcados explícitamente como false; no amplíe por su cuenta el significado de «completado».
dfc_ontology_knowledge_question_submit
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| questionRevision | $ref | Obligatorio | Versión explícita de la pregunta pendiente de confirmación actual. |
| idempotencyKey | $ref | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. |
| originalInputKey | $ref | Obligatorio | Clave de idempotencia correspondiente a la entrada de conocimiento original. |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de la autorización actual, conservado como cadena. |
| validUntil | $ref | Obligatorio | Fin de la ventana de validez de la pregunta, en hora UTC. |
| expectedRevision | oneOf | Obligatorio | Precondición de versión del resultado original o de la cabecera de negocio; puede ser null al crear la pregunta. |
| validFrom | $ref | Obligatorio | Inicio de la ventana de validez de la pregunta, en hora UTC. |
Esta herramienta cuenta además con un outputSchema nativo. Compruebe la integridad del resultado, el estado y los campos de autorización marcados explícitamente como false; no amplíe por su cuenta el significado de «completado».
dfc_ontology_business_scope_initialize
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| domainRevisionId | string | Obligatorio | Versión exacta del dominio de negocio. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Obligatorio | Clave de idempotencia reutilizada de forma estable para la misma operación lógica. minLength: 1; maxLength: 128 |
| businessSystemId | string | Obligatorio | ID real del sistema de negocio. minLength: 1 |
| ontologyId | string | Obligatorio | ID real de la ontología dentro de esta autorización, conservado como cadena. minLength: 1 |
| domainRid | string | Obligatorio | RID real del dominio de negocio. minLength: 1; maxLength: 128 |
Esta herramienta cuenta además con un outputSchema nativo. Compruebe la integridad del resultado, el estado y los campos de autorización marcados explícitamente como false; no amplíe por su cuenta el significado de «completado».
Referencia de parámetros de herramientas: espacio de trabajo de negocio
Nombres completos y campos de entrada, agrupados por herramienta.
Las siguientes tablas son una referencia de lectura de los campos de entrada de las herramientas actuales de r56. Para los tipos anidados completos, oneOf, obligatoriedad condicional, restricciones de patrón y algunos esquemas de salida, consulte reference/mcp-tool-catalog.json; antes del envío final aún debe leerse el tools/list del Grant actual. La indicación «opcional» en las tablas no elimina los requisitos de validación interna de las acciones.
dfb_systems
El objeto raíz de entrada de esta herramienta no tiene campos; use un objeto arguments vacío.
dfb_system_describe
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| systemId | string / integer | Obligatorio | ID de sistema permitido por este Grant de negocio. |
dfb_query
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| systemId | string / integer | Obligatorio | ID de sistema permitido por este Grant de negocio. |
| queryKey | string | Obligatorio | Clave de consulta publicada devuelta por describe. |
| objectKey | string | Opcional u obligatorio condicional | Clave del objeto publicado. |
| pageSize | integer | Opcional u obligatorio condicional | Número de registros por página; según el límite superior del esquema. minimum: 1; maximum: 100 |
| page | integer | Opcional u obligatorio condicional | Número de página, comenzando en 1. minimum: 1 |
| state | string | Opcional u obligatorio condicional | Filtro de estado de negocio o estado del servidor. |
dfb_record
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| recordId | string / integer | Obligatorio | ID del registro de negocio cuya lectura está permitida actualmente. |
| systemId | string / integer | Obligatorio | ID de sistema permitido por este Grant de negocio. |
dfb_work_items
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| systemId | string / integer | Obligatorio | ID de sistema permitido por este Grant de negocio. |
dfb_action_plan
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| expectedRecordVersion | integer | Opcional u obligatorio condicional | Versión actual del bloqueo optimista del registro de destino. minimum: 1 |
| systemId | string / integer | Obligatorio | ID de sistema permitido por este Grant de negocio. |
| commandType | string | Obligatorio | Tipo de comando del contrato publicado. |
| canonicalIrHash | string | Obligatorio | Hash del IR canónico de la publicación actual. |
| releaseId | string / integer | Obligatorio | ID real de la versión del contrato publicado. |
| payload | object | Obligatorio | Carga útil conforme al contrato de comando actual de describe. |
| releaseHash | string | Obligatorio | Hash real del contrato publicado. |
| targetRecordId | string / integer | Opcional u obligatorio condicional | Registro de destino real sobre el que se debe operar. |
| agentManifestHash | string | Obligatorio | Hash real del manifest de capacidades del Agent. |
| planIdempotencyKey | string | Obligatorio | Clave de idempotencia estable del plan de negocio. |
dfb_action_status
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| actionPlanId | string / integer | Obligatorio | ID del plan de acción que pertenece al Grant de negocio actual. |
dfb_action_execute
| Parámetro | Tipo | Requisito | Significado y alcance |
|---|---|---|---|
| approvalToken | string | Opcional u obligatorio condicional | Material de aprobación emitido por el servidor original; está prohibido generarlo por cuenta propia. |
| actionPlanId | string / integer | Obligatorio | ID del plan de acción que pertenece al Grant de negocio actual. |