Documentación
asistente de IA
Conversaciones relacionadas con el proyecto, acciones CAD/CAM escritas, permisos explícitos y credenciales de proveedor administradas por la aplicación.
La traducción automática no está disponible ahora; el texto está en inglés con la interfaz en tu idioma. Ver el original en inglés
Servicios de asistente
@cadcamfun/ai proporciona acceso al modelo, eventos de conversación, catálogo de acciones, indicaciones, habilidades, ensamblaje de contexto e integración de host. El motor de conversación predeterminado está integrado en nikcli; AI SDK v7 proporciona mensajes de texto directos, streaming y llamadas de salida estructurada. El sidecar inyecta controladores para mutaciones de proyectos, bibliotecas, historial y almacenamiento de aplicaciones.
Chat puede inspeccionar y cambiar un proyecto a través de acciones registradas. La generación de títulos sin estado, el análisis de diseño, las recomendaciones de parámetros, la optimización de código G y los resúmenes de sugerencias de diseño devuelven consejos o resultados estructurados; esos métodos de servicio no guardan las ediciones del proyecto. Revise los consejos de mecanizado generados a través de CAM determinista y verificación antes de confiar en ellos.
Conversaciones y controles de sesión.
POST /api/ai/chat/stream emite eventos escritos para texto, razonamiento, estado de giro/paso, llamadas y resultados de herramientas, diagnósticos, preguntas, solicitudes de permiso, reintentos, cambios de contexto, objetivos, finalización y errores. Los identificadores de sesión del cliente están vinculados a las sesiones del anfitrión y se comparan con su proyecto. Conserve el ID de la sesión para continuar la misma conversación.
POST /api/ai/sessions/state recupera el estado de ocupación, el texto acumulado y la información de la tarea después de una transmisión desconectada. /api/ai/chat/queue admite un seguimiento de una conversación activa; /api/ai/chat/abort detiene el turno y sus trabajadores asociados. Al eliminar una sesión, se cancelan y se unen sus elementos secundarios antes de eliminar la sesión del anfitrión.
/api/ai/sessions/control admite estado, inspección detallada del contexto, compactación, consolidación de memoria, cancelación de tareas, decisiones de permisos y respuesta o rechazo de preguntas pendientes. Las solicitudes se comparan con la conversación principal y las sesiones secundarias admitidas. Una pregunta que ya no está pendiente no se puede responder reutilizando su antiguo identificador.
Las llamadas de modelo directo reintentan fallas transitorias del proveedor con la misma curva que nikcli: el primer retraso es de 2 segundos y se duplica en cada intento, el propio de un proveedor. retry-after se respeta el encabezado y, sin dicho encabezado, el retraso nunca excede los 30 segundos. Por defecto, una solicitud realiza como máximo cinco llamadas, incluida la primera; el retryAttempts la configuración puede anular esto (packages/ai/src/retry.ts, direct-model.ts). Cuando la conexión del modelo se interrumpe a mitad del turno, el bucle de chat se reanuda hasta cinco veces con el mismo retraso de 2–30 segundos y le pide al modelo que continúe sin repetir los pasos completados.
Proveedores y credenciales
GET /api/ai/providers enumera los metadatos del proveedor y el estado configurado; GET /api/ai/models expone el catálogo del selector de modelos con opciones configuredOnly=true. Las lecturas del catálogo del host integrado se almacenan en caché durante un minuto. La configuración y la política afectan qué proveedores se enumeran y se pueden utilizar.
Establecer credenciales con PUT /api/ai/credentials y eliminarlos con DELETE /api/ai/credentials/:provider. Las claves no deben estar vacías y la URL base proporcionada debe ser HTTP o HTTPS. La fábrica de modelos directos admite Anthropic, OpenAI, MiniMax y AI gateway. Otros ID de proveedores requieren una URL base compatible con OpenAI para llamadas directas. El host integrado utiliza su propio catálogo de proveedores y enrutamiento.
El sidecar conserva las credenciales en <dataDir>/ai/credentials.json usando un archivo temporal, modo solo propietario 0600 y cambie el nombre. Un archivo faltante o dañado se lee como vacío. Una escritura persistente fallida deja la clave disponible para el proceso actual, pero no garantiza que sobreviva al reinicio. Las respuestas de estado exponen el estado de la configuración en lugar de las claves sin formato.
Las credenciales se representan con Redacted servicios internos y se propaga al host a través de un receptor de credenciales con alcance. Al cerrar el alcance se borra la copia del host. Los cambios de credenciales actualizan una revisión utilizada para distinguir los resultados sin estado almacenados en caché.
El nivel de modelo predeterminado es balancedy las solicitudes MiniMax van a https://api.minimax.io/v1 a menos que CADCAMFUN_AI_MINIMAX_BASE_URL lo anula (packages/ai/src/models.ts). El catálogo de modelos está sembrado del público. https://models.dev/api.json punto final solo cuando falta el archivo en caché y se permite el acceso a la red; no se envían credenciales, las respuestas tienen un límite de 8 MiB y un cuerpo que enumera menos de 20 proveedores se rechaza como truncado.
Acciones y permisos
El catálogo de acciones declara cada identificador de acción, esquema de parámetro, efecto y ruta de ejecución. Las herramientas agrupan acciones relacionadas detrás de un requisito. action campo. El host valida la entrada de la herramienta y los controladores complementarios realizan la validación del dominio y las comprobaciones de acceso a los recursos antes de persistir los cambios.
Los modos de permiso son approve, ask, y auto. Afectan la forma en que se admiten las llamadas a herramientas ordinarias; Las herramientas que contienen acciones destructivas conservan una regla de aprobación humana en todos los modos. Una bandera de entrada como confirm: true no reemplaza esa solicitud de permiso. El host no expone herramientas de edición de archivos o shell sin restricciones como sustitutos de las acciones de la aplicación.
Políticas en <dataDir>/ai/policy.json restringir el uso del proveedor, el uso de herramientas y el acceso al puente. Se cargan mediante la configuración del servicio; No asuma que editar el archivo actualiza un servicio que ya se está ejecutando. Los directorios temporales con ámbito de proyecto y la configuración aislada de nikcli mantienen el host incorporado separado del estado del agente independiente del usuario.
Las habilidades proporcionan guías de CAD/CAM e instrucciones escritas por el usuario. Guían el uso de herramientas existentes; Agregar una habilidad no agrega una nueva API de mutación. Los puntos finales HTTP de habilidades enumeran, guardan y eliminan el contenido de habilidades del usuario admitido.
Grupos de herramientas registrados
Los grupos integrados son cad, cad_edit, cam, cam_edit, library, parts, library_edit, memory, memory_edit, research, vcs, vcs_edit, y agent. cam_verify expone el subconjunto de generación y verificación que necesita la función de verificador sin otorgar la herramienta de edición CAM completa.
La agrupación de herramientas conserva los límites de los efectos. La inspección de geometría de solo lectura, la búsqueda de biblioteca y la recuperación de memoria son independientes de los cambios en esos recursos. El registro inyectado también puede admitir herramientas de extensión; Se rechazan los identificadores duplicados.
Descubre el catálogo actual
GET /api/ai/actions devuelve descripciones de herramientas, nombres y tipos de acciones y esquemas de parámetros JSON para llamantes externos. Úselo para descubrir las acciones de la aplicación en ejecución en lugar de copiar una lista estática en un cliente. POST /api/ai/actions/invoke toma un ID de proyecto, un ID de herramienta y una entrada que contiene el discriminador de acciones.
Las entradas del catálogo incorporado se mantienen en packages/ai/src/actions. Los ejemplos incluyen inspección CAD y comprobaciones paramétricas, ediciones CAD, planificación y fabricación CAM, búsquedas y actualizaciones de bibliotecas, memoria de proyectos, investigación y propuestas de VCS. Una contribución que requiere un servicio de aplicación devuelve un resultado no disponible cuando ese host no proporcionó su controlador.
API de integración pública
ACTION_CATALOGUE, ACTION_TOOL_IDS, EXPOSED_TOOL_IDS, actionById, toolKind, y runAction apoyar a los consumidores del catálogo. ToolHandlers es el contrato de integración de sidecar; ToolRegistry compone herramientas integradas y de extensión. AiService proporciona conversaciones, metadatos de modelos, llamadas únicas y operaciones de sesión.
assembleContext compone el contexto de turno con un presupuesto agregado predeterminado de 24,000 caracteres. Ordena requisitos permanentes, observaciones actuales, instantáneas de la interfaz de usuario, memoria y referencias de respaldo, deduplica por identidad y contenido, y registra fuentes omitidas o truncadas. Este presupuesto de contexto es independiente de la ventana de token completa del modelo y del umbral de compactación del host.
Trabajo de antecedentes y evidencia.
El programador de tiempo de ejecución permite cuatro tareas activas en segundo plano y dieciséis tareas en cola. Las tareas pertenecen a un proyecto y a una sesión principal. La cancelación conserva la propiedad activa hasta que un trabajador cese; detener o eliminar el padre también detiene su trabajo asociado. La recuperación del trabajador de lectura está limitada a dos intentos, mientras que el trabajo de edición interrumpido se marca como incierto en lugar de reproducirse a ciegas.
El éxito de la herramienta asistente es un resultado que se debe inspeccionar. Las operaciones CAD pueden devolver diagnósticos de geometría parciales; Los artefactos CAM tienen sus propios reclamos y niveles de liberación; Los servicios de historial hacen cumplir las sucursales protegidas. El texto de una conversación, una tarea marcada como completada y el resultado de una verificación geométrica describen evidencia diferente.
El contexto del proyecto enviado al modelo está presupuestado: un documento de contexto del proyecto almacenado puede contener hasta 8,000 caracteres, de los cuales 2,000 llegan al mensaje, con 1,500 caracteres cada uno para la memoria del proyecto y los hábitos del usuario. Las notas del proyecto con más de 90 días a las que el contexto del proyecto no hace referencia se eliminan cuando se establece una sesión (packages/ai/src/project-context.ts).
Selección de tiempo de ejecución
CADCAMFUN_AI_HOST selecciona nikcli por defecto o direct. La ruta directa utiliza llamadas AI SDK sin el bucle de herramientas de agente persistente y el programador especializado del host integrado. Las operaciones sin estado utilizan el servicio de modelo directo incluso cuando el host integrado está habilitado.
Los directorios XDG del host y la anulación de inicio opcional están enraizados en <dataDir>/ai/nikcli. La carga de la configuración del proyecto y las configuraciones heredadas del agente no relacionadas se deshabilitan o se eliminan antes de la importación del SDK. Su espacio de trabajo es un directorio temporal de la aplicación por proyecto, en lugar del directorio fuente del usuario.
Acceso independiente a nikcli
@cadcamfunv2/cadcamfun-nikcli-plugin conecta un nikcli independiente a una aplicación en ejecución. Configurar su url, tokeny predeterminado projectId, o usar CADCAMFUN_URL, CADCAMFUN_TOKEN, y CADCAMFUN_PROJECT. Proporcione un token de puente con ámbito emitido por la aplicación para acceso externo.
Los tokens de puente están restringidos a un proyecto y a acciones de solo lectura o lectura/escritura. De forma predeterminada, son 30 días, permiten entre 1 y 365 días, se pueden enumerar y revocar y revelan su secreto solo cuando se emiten. Admiten únicamente las dos vías del puente de actuación. Las políticas pueden limitar aún más las herramientas y acciones visibles.
El complemento recupera el catálogo de la aplicación y convierte sus esquemas en argumentos de la herramienta nikcli. Las acciones destructivas se rechazan incluso con una bandera de confirmación, y el proceso agent la herramienta de delegación está excluida. Las herramientas de extensión de complementos con capacidad de escritura no están expuestas a través de este puente externo. HTTP 401 informa un token rechazado; los rechazos de acciones devuelven resultados de error legibles.
Mapa de implementación
service.ts posee operaciones de IA orientadas a aplicaciones; direct-model.ts posee llamadas AI SDK; credentials.ts posee un estado clave; nikcli/ posee aislamiento, sesiones, políticas, contexto y trabajadores; actions/ y tools/ propias definiciones de capacidad y adaptadores. Sidecar services/ai.ts manipuladores y almacenamiento de proyectos de cables. packages/nikcli-plugin posee el cliente HTTP externo.
Iniciar y recuperar una conversación
Con un sidecar en ejecución y un modelo configurado, esta solicitud abre una conversación sin inyectar el contexto del espacio de trabajo almacenado. Colocar CADCAMFUN_URL a la URL base de loopback descubierta y CADCAMFUN_TOKEN a su token de aplicación actual. El identificador de sesión siguiente es seleccionado por el cliente; guárdelo para seguimientos.
curl --no-buffer --fail-with-body \
-H "Authorization: Bearer $CADCAMFUN_TOKEN" \
-H "Content-Type: application/json" \
--data '{"message":"Explain the difference between G0 and G1.","sessionId":"inspection-demo","includeContext":false,"mode":"gcode"}' \
"$CADCAMFUN_URL/api/ai/chat/stream"Para un turno de proyecto, proporcione también su valor real. projectId, y opcionalmente un drawingId perteneciente a ese proyecto. El dibujo vincula las herramientas del turno a ese dibujo. Se rechaza la reutilización de una sesión en otro proyecto o cuenta.
curl --fail-with-body \
-H "Authorization: Bearer $CADCAMFUN_TOKEN" \
-H "Content-Type: application/json" \
--data '{"sessionId":"inspection-demo"}' \
"$CADCAMFUN_URL/api/ai/sessions/state"el regresado busy, text, opcional events, y tasks reconstruir la vista; reproducir esos eventos almacenados no vuelve a ejecutar las herramientas. Para detener el trabajo, envíe un aborto explícito. Cerrar la transmisión por sí solo no une a los trabajadores de la conversación.
Fuente: packages/api/src/groups/ai.ts, apps/sidecar/src/http/ai.ts, y packages/ai/src/service.ts.
Manejar eventos sin perder estado
| Evento | Comportamiento del consumidor |
|---|---|
delta / reasoning | Añadir text al canal de texto o razonamiento de la sesión de emparejamiento. |
tool_call / tool_result | Correlacionar por callId; inspeccionar ok y conservar los diagnósticos independientemente del texto asistente. |
permission_request | Muestre la solicitud y responda con sus ID de solicitud/sesión y once, always, o reject. |
question_request | Conserve su ID de solicitud y sus preguntas; envíe una matriz de respuestas por pregunta a través de los controles de sesión. |
done | utilizar final text y uso opcional como respuesta completa; no agregue el texto final completo a los deltas ya acumulados. |
error | Mostrar message con config, provider, aborted, o internal clasificación. |
heartbeat | Mantenga viva la conexión sin agregar contenido ni declarar el turno completo. |
Los controles de sesión aceptan solo ID de preguntas/permisos pendientes en esa conversación o sus sesiones secundarias. Una pregunta requiere respuestas que no estén vacías; una pregunta de opción única rechaza varios valores seleccionados, y una pregunta que no permite respuestas personalizadas acepta solo las etiquetas de opciones enumeradas.
Fuente: packages/api/src/ai-events.ts, packages/ai/src/nikcli/session-controls.ts, y packages/ai/src/heartbeat.ts.
Archivos adjuntos y habilidades de usuario
Cada solicitud de chat acepta hasta cinco archivos adjuntos. Las imágenes admitidas son PNG, JPEG, WebP y GIF, con un límite de 5 MiB cada una; Los archivos PDF tienen un límite de 10 MiB. Los archivos adjuntos de texto aceptan hasta 2,000,000 caracteres, y textos de hasta 6,000 caracteres también se incluyen en línea. Los archivos no compatibles generan un motivo de rechazo en lugar de desaparecer silenciosamente.
Los archivos adjuntos de texto se guardan en un almacén en memoria del proyecto para herramientas de importación: como máximo 32 nombres y 8,000,000 caracteres por proyecto y 32,000,000 caracteres en como máximo 64 proyectos almacenados. Reutilizar un nombre reemplaza su texto anterior. Al reiniciar el servicio no se conserva este almacén de archivos adjuntos. La transformación del proveedor informa al modelo de una discrepancia en la capacidad de PDF.
Los nombres de habilidades de usuario son palabras con letras o dígitos en minúscula unidas por guiones, como máximo 64 caracteres. Los límites de descripción y cuerpo son 300 y 20,000 caracteres respectivamente; como máximo se pueden cargar 50 habilidades de usuario. Las habilidades integradas no se pueden eliminar a través de la API de habilidades del usuario. Una habilidad guardada live el resultado indica si la recarga del host tuvo efecto.
Fuente: packages/ai/src/attachments.ts, packages/ai/src/skills/user.ts, y apps/sidecar/src/http/ai.ts.
Diagnosticar fallas del asistente
- Sin modelo configurado: inspeccionar
/api/ai/statusy/api/ai/providersy luego establezca una clave para un proveedor listado. Un indicador configurado demuestra que existe una clave almacenada, no que el proveedor la aceptó. - Proveedor desconocido o URL no válida: utilice un ID de proveedor anunciado y una URL base HTTP(S). Un proveedor directo no integrado necesita un punto final compatible además de su clave.
- Sesión inaccesible: recuperar utilizando la identidad original del proyecto/cuenta/sesión. No invente un ID de proyecto de reemplazo para una sesión de host existente.
- Un turno espera indefinidamente: inspeccione el estado de control de la sesión en busca de permisos pendientes o preguntas antes de volver a intentar un mensaje duplicado. Utilice el aborto explícito para cancelar el turno y unirse a sus trabajadores.
- Una herramienta cambió parcialmente el modelo: inspeccionar su
tool_diagnostic, incluidomutationApplied, luego lea el dibujo actual. Reintentar una acción de edición sin inspeccionar su resultado puede duplicar la geometría.
Los resultados de la herramienta y los errores escritos conservan la etapa que falló. Un error del proveedor después de herramientas exitosas no revierte esas mutaciones del proyecto. Las comprobaciones deterministas de historial y CAM siguen estando disponibles por separado de la respuesta del modelo.
Referencia del punto final del asistente
Todas las rutas de asistente viven bajo /api/ai y requiere el token de portador de la aplicación. Un token de puente para un nikcli independiente abre solo la lista de acciones y las rutas de invocación, y solo para su proyecto.
| Ruta | Objetivo |
|---|---|
POST /api/ai/chat/stream | Iniciar un turno de transmisión; la respuesta es un flujo SSE de eventos asistentes. |
POST /api/ai/chat/queue | Ponga en cola un mensaje de seguimiento para una sesión ocupada. |
POST /api/ai/chat/abort | Cancelar el turno en ejecución de una sesión. |
POST /api/ai/permission/reply | Responder una solicitud de permiso: once, always, o reject. |
POST /api/ai/sessions/state, /sessions/control, /sessions/remove | Leer el estado de la sesión, controlar una sesión, eliminar una. |
GET /api/ai/status, /models, /providers, /agents, /prompts | Descubrimiento: preparación, catálogo de modelos, proveedores con su estado de configuración, agentes especializados, sugerencias rápidas. |
PUT /api/ai/credentials, DELETE /api/ai/credentials/:provider | Almacene o borre las credenciales del proveedor. |
GET/PUT /api/ai/skills, DELETE /api/ai/skills/:name | Enumere, guarde y elimine habilidades de usuario. |
GET /api/ai/actions, POST /api/ai/actions/invoke | Catálogo de acciones e invocación directa (también utilizado por el puente nikcli). |
GET/POST /api/ai/bridge/tokens, DELETE /api/ai/bridge/tokens/:id | Emitir, enumerar y revocar tokens de puente con ámbito. |
POST /api/ai/completion | Finalización única: prompt, systemPrompt, model, temperature; regresa text y model. |
POST /api/ai/title | Título de un extracto de conversación. |
POST /api/ai/design-analysis | Sugerencias con confidence, priority (bajo/medio/alto), y kind (optimización/advertencia/crítico). |
POST /api/ai/machining-parameters | Cutting speed (m/min), feed (mm/min), depth of cut (mm), stepover (%), coolant (flood/mist/none), engagement (conventional/climb), and warnings. |
POST /api/ai/gcode-optimization | Código G optimizado con cambios y motivos por línea, tiempo estimado y ahorro de vida útil de la herramienta, y notas. |
POST /api/ai/design-suggestions | Sugerencias para el siguiente paso con título, justificación y siguiente paso. |
POST /api/ai/analyze-gcode | Problemas (error/advertencia/información con código, línea y mensaje) y estadísticas: líneas, movimientos rápidos y de corte, cambios de herramientas y límites. |
POST /api/ai/gcode, /toolpath-analysis, /feedback, /proxy | Acciones de código G, información sobre trayectorias de herramientas, comentarios y proxy del proveedor. |
Las respuestas del análisis respaldado por modelos son resultados del modelo en una forma escrita. Valores como los parámetros de mecanizado son sugerencias para revisar con datos de herramientas y límites de la máquina, no datos de corte verificados.
Campos de solicitud de transmisión
| Campo | Valores | Effect |
|---|---|---|
message | cadena | El mensaje del usuario para este turno. |
sessionId | cadena | Continuar una sesión existente; omita comenzar uno nuevo. |
projectId | cadena | Proyecto cuyo contexto y herramientas utiliza el turno. |
drawingId | cadena | El dibujo sobre el que este turno puede actuar. Se compara con el proyecto antes de admitir el giro, y las herramientas del giro actúan sobre este dibujo y nada más. |
mode | general, cad, cam, gcode, toolpath | Enfoque del turno. |
permissionMode | auto, ask, approve | Cómo se solicitan los permisos de las herramientas. |
agent | cadena | Nombre del agente especialista de /api/ai/agents. |
attachments | [{ name, mime?, data, encoding?: "base64" | "text" }] | Hasta 5 archivos adjuntos: imágenes de hasta 5 MB, archivos PDF de hasta 10 MB y texto de hasta 2,000,000 caracteres (también se escriben archivos de texto de hasta 6,000 caracteres en el mensaje). |
context, includeContext | cadena, booleano | Texto de contexto adicional y si se debe incluir el contexto del proyecto ensamblado. |
model | selector de modelo | Anula el modelo configurado para este turno. |
Límites y valores predeterminados
| Límite | Valor |
|---|---|
| Presupuesto de contexto ensamblado | 24,000 caracteres; un bloque que no encaja se trunca con un marcador y un bloque que se cortaría por debajo de 400 caracteres se omite en su lugar |
| Documento de contexto del proyecto | Hasta 8,000 caracteres almacenados, 2,000 enviados al modelo |
| Memoria del proyecto/hábitos del usuario | 1,500 characters each |
| Notas del proyecto | Podado después de 90 días cuando el contexto del proyecto no hace referencia a él |
| Salida de herramienta enviada al modelo. | 24,000 caracteres |
| Elementos creados por llamada | 40 |
| Fichas de salida | 32,000 máximo |
| Latido del corazón | Cada 5 segundos mientras la transmisión esté activa |
| Acciones de geometría exacta | 60-segundo presupuesto; exact reports 1.5 seconds |
| Empleos de kernel | 120-second deadline, worker start included |
| Tareas en segundo plano | 4 activo, 16 en cola, 2 intentos de trabajadores de lectura, tareas resueltas mantenidas 7 días |
| Continuaciones automáticas | 50 por solicitud; La conexión 5 se reanuda con una interrupción de 2-30 |
| Reintentos de llamada directa | 5 llamadas incluida la primera; 2 s duplicando a 30 s, respetando retry-after |
| Habilidades de usuario | 50 habilidades; nombre hasta 64 caracteres (palabras minúsculas unidas por guiones), descripción hasta 300, cuerpo hasta 20,000 |
| Recuperación de búsqueda web | 256 KB por respuesta |
| Fichas de puente | 30 días de forma predeterminada, 365 días como máximo |
Lea el resultado, no la prosa.
El resultado de una herramienta está en tool_result y tool_diagnostic eventos. Compruebe si se aplicó una mutación antes de confiar en el resumen del asistente sobre lo que hizo.
El catálogo de acciones completo
El asistente actúa a través de 83 acciones declaradas en 13 familias. Cada acción declara su esquema de resultados y su efectos: lo que cambia o alcanza más allá de la lectura del documento abierto. Leer familias (cad, cam, library, memory, research, vcs) en su mayoría no tienen ningún efecto; su _edit las contrapartes cambian de estado persistente. Los efectos se enumeran entre paréntesis.
| Familia | Contar | Acciones (efectos) |
|---|---|---|
cad | 20 | describe, check, relations, grep, vision (interfaz), inspect_elements, inspect_layers, inspect_search, inspect_property, drawing, parametric_validate, parametric_inspect, parametric_test, parametric_dfm, parametric_exact, exact, assembly, parametric_fastener, parametric_recipe, parametric_from_element |
cad_edit | 12 | add (dibujo), add_entities (dibujo), modify (dibujo), transform (dibujo), group (dibujo), delete (dibujo), editor (interfaz+dibujo), import (dibujo), parametric_create (dibujo), parametric_update (dibujo), parametric_recipe_create (dibujo), parametric_convert (dibujo) |
cam | 14 | plan_check, review, machine, operations, suggest, compare_setups, analyze, stock, vision (interfaz), chain_suggest, materials, cutting_data, manufacture, chain_status |
cam_edit | 6 | manufacture (operación+programa), create (operación), update (operación), generate (programa), verify (informe), stock_set (existencias) |
library | 5 | component_list, lookup_component, lookup_material, lookup_tool, lookup_machine_config |
parts | 3 | save (componente), insert (dibujo), delete (componente) |
library_edit | 5 | upsert_material (biblioteca), upsert_tool (biblioteca), upsert_machine_config (biblioteca), set_default (biblioteca), delete (biblioteca) |
memory | 2 | recall, context_read |
memory_edit | 2 | remember (memoria), context_update (contexto) |
research | 2 | search (externo), read_attachment |
vcs | 3 | status, diff, list_pull_requests |
vcs_edit | 5 | start_change (historia), commit (historia), restore (historia+dibujo), open_pull_request (historia), run_workflows (flujo de trabajo) |
agent | 4 | start (tarea), list, read, cancel (tarea) |
| Effect | Significado |
|---|---|
drawing, component, operation, program, stock, report | Datos persistentes de diseño o fabricación. |
library, memory, context | Registros de biblioteca, memoria de proyecto, contexto del espacio de trabajo |
history, workflow | Control de versiones y ejecuciones de flujo de trabajo |
task | El planificador de delegación (agentes en segundo plano) |
interface | El editor o ventana gráfica en pantalla; no persistente |
external | La red (investigación web) |
Una acción de lectura sólo puede tener interface o external; cada escritura nombra al menos un efecto persistente. Los efectos se declaran por acción y nunca se infieren de la herramienta que los implementa.
Cómo termina una llamada a la acción
| Resultado | Cuando |
|---|---|
succeeded | La acción hizo lo que se pidió. Incluye lecturas con un resultado negativo, como una verificación fallida. |
partial | Parte de la respuesta o lote: complete: false, omitted > 0, no vacío skipped, o un nextOffset a la página en |
refused | Nada hecho: ok: false con un error o etiqueta (entrada no válida, denegada, no disponible, nada que hacer) |
conflict | El documento continuó: ActionConflict o estado stale/conflict. Inspeccione nuevamente antes de volver a intentarlo. |
cancelled | ActionInterrupted |
uncertain | ActionUncertain: es posible que se haya cometido una escritura pero no se pudo leer su respuesta. Conciliar inspeccionando; nunca vuelvas a intentarlo a ciegas. |
Los escritos están sujetos a una revisión del dibujo. Una escritura confirmada devuelve un ActionCommitted recibo con previousRevision y revision; una escritura contra un rancio expectedRevision regresa ActionConflict con ambos expectedRevision y actualRevision. La misma clasificación (actionOutcome) es compartido por el host, el modo de código, el escritorio y el puente.
{
"ok": false,
"_tag": "ActionConflict",
"actionId": "cad_edit.modify",
"projectId": "…", "drawingId": "…",
"expectedRevision": 41, "actualRevision": 42,
"message": "…"
}