Assistente de IA

Serviços de assistente

@cadcamfun/ai fornece acesso ao modelo, eventos de conversação, catálogo de ações, prompts, habilidades, montagem de contexto e integração de host. O mecanismo de conversação padrão é o nikcli incorporado; O AI SDK v7 fornece texto direto, streaming e chamadas de saída estruturada. O sidecar injeta manipuladores para mutações de projetos, bibliotecas, histórico e armazenamento de aplicativos.

O Chat pode inspecionar e alterar um projeto através de ações cadastradas. Geração de títulos sem estado, análise de design, recomendações de parâmetros, otimização de código G e resumos de sugestões de design retornam conselhos ou resultados estruturados; esses métodos de serviço não salvam as edições do projeto. Revise os conselhos de usinagem gerados por meio de CAM determinístico e verificação antes de confiar neles.

Conversas e controles de sessão

POST /api/ai/chat/stream emite eventos digitados para texto, raciocínio, estado de giro/etapa, chamadas e resultados de ferramentas, diagnósticos, perguntas, solicitações de permissão, novas tentativas, mudanças de contexto, metas, conclusão e erros. Os identificadores de sessão do cliente são vinculados às sessões do host e verificados em relação ao seu projeto. Guarde o ID da sessão para continuar a mesma conversa.

POST /api/ai/sessions/state recupera estado ocupado, texto acumulado e informações de tarefas após um fluxo desconectado. /api/ai/chat/queue admite seguimento a uma conversa ativa; /api/ai/chat/abort interrompe o turno e seus trabalhadores associados. A remoção de uma sessão cancela e ingressa em seus filhos antes de remover a sessão do host.

/api/ai/sessions/control suporta status, inspeção detalhada de contexto, compactação, consolidação de memória, cancelamento de tarefas, decisões de permissão e resposta ou rejeição de questões pendentes. As solicitações são verificadas em relação à conversa pai e às sessões filhas admitidas. Uma questão que não está mais pendente não pode ser respondida reutilizando seu antigo identificador.

As chamadas de modelo direto tentam novamente falhas transitórias do provedor com a mesma curva do nikcli: o primeiro atraso é de 2 segundos e dobra em cada tentativa, o próprio provedor retry-after o cabeçalho é respeitado e, sem esse cabeçalho, o atraso nunca excede 30 segundos. Por padrão, uma solicitação faz no máximo cinco chamadas, incluindo a primeira; o retryAttempts configuração pode substituir isso (packages/ai/src/retry.ts, direct-model.ts). Quando a conexão do modelo cai no meio do turno, o loop de bate-papo é retomado até cinco vezes com a mesma espera de 2–30 segundos e solicita que o modelo continue sem repetir as etapas concluídas.

Provedores e credenciais

GET /api/ai/providers lista os metadados do provedor e o estado configurado; GET /api/ai/models expõe o catálogo do seletor de modelo com opcional configuredOnly=true. As leituras do catálogo de host incorporado são armazenadas em cache por um minuto. A configuração e a política afetam quais provedores são listados e utilizáveis.

Definir credenciais com PUT /api/ai/credentials e remova-os com DELETE /api/ai/credentials/:provider. As chaves não devem estar vazias e um URL base fornecido deve ser HTTP ou HTTPS. A fábrica de modelos diretos suporta Anthropic, OpenAI, MiniMax e o gateway AI. Outros IDs de provedor exigem uma URL base compatível com OpenAI para chamadas diretas. O host incorporado usa seu próprio catálogo de provedores e roteamento.

O sidecar persiste credenciais em <dataDir>/ai/credentials.json usando um arquivo temporário, modo somente proprietário 0600 e renomeie. Um arquivo ausente ou danificado é considerado vazio. Uma falha na gravação de persistência deixa a chave disponível para o processo atual, mas não garante que ela sobreviva à reinicialização. As respostas de status expõem o estado da configuração em vez das chaves brutas.

As credenciais são representadas com Redacted dentro dos serviços e propagado para o host por meio de um coletor de credenciais com escopo definido. Fechar o escopo limpa a cópia do host. As alterações de credenciais atualizam uma revisão usada para distinguir resultados sem estado armazenados em cache.

A camada de modelo padrão é balanced, e as solicitações MiniMax vão para https://api.minimax.io/v1 a menos que CADCAMFUN_AI_MINIMAX_BASE_URL substitui-lo (packages/ai/src/models.ts). O catálogo de modelos é propagado pelo público https://models.dev/api.json endpoint somente quando o arquivo em cache estiver ausente e o acesso à rede for permitido; nenhuma credencial é enviada, as respostas são limitadas a 8 MiB e um corpo listando menos de 20 provedores é rejeitado como truncado.

Ações e permissões

O catálogo de ações declara cada identificador de ação, esquema de parâmetro, efeito e caminho de execução. As ferramentas agrupam ações relacionadas por trás de um item obrigatório action campo. O host valida a entrada da ferramenta e os manipuladores secundários realizam validação de domínio e verificações de acesso a recursos antes de persistir as alterações.

Os modos de permissão são approve, ask, e auto. Eles afetam a forma como as chamadas de ferramentas comuns são admitidas; ferramentas contendo ações destrutivas mantêm uma regra de aprovação humana em todos os modos. Um sinalizador de entrada como confirm: true não substitui essa solicitação de permissão. O host não expõe shell irrestrito ou ferramentas de edição de arquivos como substitutos para ações do aplicativo.

Políticas em <dataDir>/ai/policy.json restringir o uso do provedor, o uso de ferramentas e o acesso à ponte. Eles são carregados pela configuração do serviço; não presuma que a edição do arquivo atualiza um serviço já em execução. Os diretórios temporários no escopo do projeto e a configuração isolada do nikcli mantêm o host incorporado separado do estado do agente autônomo do usuário.

As habilidades fornecem manuais de CAD/CAM e instruções de autoria do usuário. Eles orientam o uso das ferramentas existentes; adicionar uma habilidade não adiciona uma nova API de mutação. Os pontos de extremidade HTTP de habilidades listam, salvam e excluem o conteúdo de habilidade do usuário compatível.

Grupos de ferramentas registrados

Os grupos integrados são cad, cad_edit, cam, cam_edit, library, parts, library_edit, memory, memory_edit, research, vcs, vcs_edit, e agent. cam_verify expõe o subconjunto de geração e verificação necessário para a função de verificador sem conceder a ferramenta de edição CAM completa.

O agrupamento de ferramentas preserva os limites do efeito. A inspeção de geometria somente leitura, a pesquisa de biblioteca e a recuperação de memória são separadas das alterações nesses recursos. O registro injetado também pode admitir ferramentas de extensão; identificadores duplicados são rejeitados.

Descubra o catálogo atual

GET /api/ai/actions retorna descrições de ferramentas, nomes e tipos de ações e esquemas de parâmetros JSON para chamadores externos. Use-o para descobrir as ações do aplicativo em execução, em vez de copiar uma lista estática em um cliente. POST /api/ai/actions/invoke recebe um ID do projeto, um ID da ferramenta e uma entrada contendo o discriminador de ação.

As entradas de catálogo integradas são mantidas em packages/ai/src/actions. Os exemplos incluem inspeção CAD e verificações paramétricas, edições CAD, planejamento e fabricação CAM, pesquisa e atualizações de bibliotecas, memória de projetos, pesquisas e propostas VCS. Uma contribuição que exige um serviço de aplicativo retorna um resultado indisponível quando o host não fornece seu manipulador.

APIs de integração pública

ACTION_CATALOGUE, ACTION_TOOL_IDS, EXPOSED_TOOL_IDS, actionById, toolKind, e runAction oferecer suporte aos consumidores do catálogo. ToolHandlers é o contrato de integração sidecar; ToolRegistry compõe ferramentas integradas e de extensão. AiService fornece conversas, metadados de modelo, chamadas únicas e operações de sessão.

assembleContext compõe o contexto do turno com um orçamento agregado padrão de 24,000 caracteres. Ele ordena requisitos permanentes, observações atuais, instantâneos de UI, memória e referências de suporte, desduplica por identidade e conteúdo e registra fontes omitidas ou truncadas. Esse orçamento de contexto é separado da janela de token completa do modelo e do limite de compactação do host.

Trabalho de base e evidências

O agendador de tempo de execução permite quatro tarefas ativas em segundo plano e dezesseis tarefas enfileiradas. As tarefas pertencem a um projeto e a uma sessão pai. O cancelamento mantém a propriedade ativa até que um trabalhador pare; interromper ou excluir o pai também interrompe o trabalho associado. A recuperação do trabalhador de leitura é limitada a duas tentativas, enquanto o trabalho de edição interrompido é marcado como incerto em vez de reproduzido cegamente.

O sucesso da ferramenta assistente é um resultado a ser inspecionado. As operações CAD podem retornar diagnósticos de geometria parcial; Os artefatos CAM carregam suas próprias reivindicações e níveis de liberação; os serviços de histórico impõem ramificações protegidas. O texto da conversa, uma tarefa marcada como concluída e um resultado de verificação geométrica descrevem diferentes evidências.

O contexto do projeto enviado ao modelo é orçado: um documento de contexto do projeto armazenado pode conter até 8,000 caracteres, dos quais 2,000 chegam ao prompt, com 1,500 caracteres cada para memória do projeto e hábitos do usuário. As notas do projeto com mais de 90 dias às quais o contexto do projeto não faz referência são removidas quando uma sessão é estabelecida (packages/ai/src/project-context.ts).

Seleção de tempo de execução

CADCAMFUN_AI_HOST seleciona nikcli por padrão ou direct. O caminho direto usa chamadas do AI SDK sem o loop de ferramenta de agente persistente do host incorporado e o agendador especializado. As operações sem estado usam o serviço de modelo direto mesmo quando o host incorporado está habilitado.

Os diretórios XDG do host e a substituição inicial opcional estão enraizados em <dataDir>/ai/nikcli. O carregamento da configuração do projeto e as configurações do agente herdado não relacionado são desabilitadas ou limpas antes da importação do SDK. Seu espaço de trabalho é um diretório inicial do aplicativo por projeto, em vez do diretório de origem do usuário.

Acesso nikcli independente

@cadcamfunv2/cadcamfun-nikcli-plugin conecta um nikcli independente a um aplicativo em execução. Configure seu url, tokene padrão projectId, ou usar CADCAMFUN_URL, CADCAMFUN_TOKEN, e CADCAMFUN_PROJECT. Forneça um token de ponte com escopo emitido pelo aplicativo para acesso externo.

Os tokens de ponte são restritos a um projeto e ações somente leitura ou leitura/gravação. Eles padronizam 30 dias, permitem 1–365 dias, podem ser listados e revogados e revelam seu segredo somente quando emitidos. Admitem apenas as duas rotas da ponte de ação. A política pode restringir ainda mais as ferramentas e ações visíveis.

O plugin busca o catálogo do aplicativo e converte seus esquemas em argumentos da ferramenta nikcli. Ações destrutivas são recusadas mesmo com um sinalizador de confirmação, e as ações em processo agent a ferramenta de delegação está excluída. Ferramentas de extensão de plug-in com capacidade de gravação não são expostas por meio dessa ponte externa. HTTP 401 relata um token rejeitado; recusas de ação retornam resultados de falha legíveis.

Mapa de implementação

service.ts possui operações de IA voltadas para aplicativos; direct-model.ts possui chamadas AI SDK; credentials.ts possui estado-chave; nikcli/ possui isolamento, sessões, políticas, contexto e trabalhadores; actions/ e tools/ próprias definições de capacidade e adaptadores. Sidecar services/ai.ts conecta manipuladores de projetos e armazenamento. packages/nikcli-plugin possui o cliente HTTP externo.

Iniciar e recuperar uma conversa

Com um sidecar em execução e um modelo configurado, essa solicitação abre uma conversa sem injetar contexto de espaço de trabalho armazenado. Definir CADCAMFUN_URL para o URL base de loopback descoberto e CADCAMFUN_TOKEN ao seu token de aplicativo atual. O identificador de sessão abaixo é selecionado pelo cliente; guarde-o para acompanhamento.

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 uma virada de projeto, forneça também seu valor real projectIde, opcionalmente, um drawingId pertencente a esse projeto. O desenho vincula as ferramentas do turno a esse desenho. A reutilização de uma sessão em outro projeto ou conta é recusada.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"sessionId":"inspection-demo"}' \
  "$CADCAMFUN_URL/api/ai/sessions/state"

O retornado busy, text, opcional events, e tasks reconstruir a visão; reproduzir esses eventos armazenados não executa as ferramentas novamente. Para interromper o trabalho, envie uma interrupção explícita. Fechar o stream sozinho não junta os trabalhadores da conversa.

Fonte: packages/api/src/groups/ai.ts, apps/sidecar/src/http/ai.ts, e packages/ai/src/service.ts.

Lidar com eventos sem perder estado

Os controles de sessão aceitam apenas IDs de permissão/pergunta pendentes nessa conversa ou em suas sessões secundárias. Uma pergunta requer respostas não vazias; uma pergunta de escolha única rejeita vários valores selecionados e uma pergunta que não permite respostas personalizadas aceita apenas os rótulos de opções listados.

Fonte: packages/api/src/ai-events.ts, packages/ai/src/nikcli/session-controls.ts, e packages/ai/src/heartbeat.ts.

Anexos e habilidades do usuário

Cada solicitação de chat aceita até cinco anexos. As imagens suportadas são PNG, JPEG, WebP e GIF, com limite de 5 MiB cada; PDFs têm um limite de 10 MiB. Os anexos de texto aceitam até 2,000,000 caracteres, com textos de até 6,000 caracteres também incluídos in-line. Arquivos não suportados produzem um motivo de rejeição, em vez de desaparecerem silenciosamente.

Os anexos de texto são mantidos em um armazenamento na memória com escopo de projeto para ferramentas de importação: no máximo 32 nomes e 8,000,000 caracteres por projeto e 32,000,000 caracteres em no máximo 64 projetos armazenados. A reutilização de um nome substitui seu texto anterior. Reiniciar o serviço não retém esse armazenamento de anexos. Uma incompatibilidade de capacidade PDF é relatada ao modelo pela transformação do provedor.

Os nomes de habilidades do usuário são letras minúsculas/algarismos unidos por hífens, com no máximo 64 caracteres. Os limites de descrição e corpo são 300 e 20,000 caracteres respectivamente; no máximo 50 habilidades de usuário podem ser carregadas. As habilidades integradas não podem ser removidas por meio da API de habilidades do usuário. Uma habilidade salva live o resultado indica se a recarga do host entrou em vigor.

Fonte: packages/ai/src/attachments.ts, packages/ai/src/skills/user.ts, e apps/sidecar/src/http/ai.ts.

Diagnosticar falhas do assistente

• Nenhum modelo configurado: inspecionar /api/ai/status e /api/ai/providerse defina uma chave para um provedor listado. Um sinalizador configurado prova que existe uma chave armazenada, e não que o fornecedor a aceitou.
• Provedor desconhecido ou URL inválido: use um ID de provedor anunciado e um URL base HTTP(S). Um provedor direto não integrado precisa de um endpoint compatível além de sua chave.
• Sessão inacessível: recuperar usando a identidade original do projeto/conta/sessão. Não invente um ID de projeto substituto para uma sessão de host existente.
• Uma vez espera indefinidamente: inspecione o estado do controle da sessão em busca de permissões ou perguntas pendentes antes de tentar novamente um prompt duplicado. Use abortar explícito para cancelar o turno e juntar-se aos seus trabalhadores.
• Uma ferramenta mudou parcialmente o modelo: inspecionar seu tool_diagnostic, incluindo mutationAppliede leia o desenho atual. Tentar novamente uma ação de edição sem inspecionar seu resultado pode duplicar a geometria.

Os resultados da ferramenta e as falhas digitadas preservam o estágio que falhou. Um erro do provedor após ferramentas bem-sucedidas não reverte essas mutações do projeto. As verificações determinísticas do CAM e do histórico permanecem disponíveis separadamente da resposta do modelo.

Referência de endpoint do assistente

Todas as rotas do assistente ficam em /api/ai e exigir o token de portador do aplicativo. Um token de ponte para um nikcli independente abre apenas a listagem de ações e as rotas de invocação, e apenas para seu projeto.

As respostas da análise baseada em modelo são saídas do modelo em um formato digitado. Valores como parâmetros de usinagem são sugestões para revisão em relação aos dados de ferramentas e limites da máquina, e não aos dados de corte verificados.

Campos de solicitação de streaming

Limites e padrões

O catálogo completo de ações

O assistente atua através de 83 ações declaradas em 13 famílias. Cada ação declara seu esquema de resultado e seu efeitos: o que muda ou vai além da leitura do documento aberto. Leia famílias (cad, cam, library, memory, research, vcs) em sua maioria não têm efeito; deles _edit contrapartes mudam de estado persistente. Os efeitos estão listados entre parênteses.

Uma ação de leitura só pode ter interface ou external; cada gravação nomeia pelo menos um efeito persistente. Os efeitos são declarados por ação e nunca inferidos da ferramenta que os implementa.

Como termina uma chamada de ação

As gravações estão vinculadas a uma revisão de desenho. Uma gravação confirmada retorna um ActionCommitted recibo com previousRevision e revision; uma escrita contra um obsoleto expectedRevision retorna ActionConflict com ambos expectedRevision e actualRevision. A mesma classificação (actionOutcome) é compartilhado pelo host, modo de código, desktop e ponte.

{
  "ok": false,
  "_tag": "ActionConflict",
  "actionId": "cad_edit.modify",
  "projectId": "…", "drawingId": "…",
  "expectedRevision": 41, "actualRevision": 42,
  "message": "…"
}

Em 3D