Operações do site de documentação

Arquitetura do site

packages/web é um aplicativo de saída de servidor Astro com o adaptador Cloudflare. Os artigos de documentação declaram pré-renderização e tornam-se ativos HTML estáticos. As rotas do servidor lidam com a exportação de Markdown, solicitações de assistente de documentação, visualização de artefatos/conteúdo bruto e o substituto do Studio de produção. Esta implantação é separada do sidecar CAD/CAM.

O site de documentação descreve o comportamento do aplicativo e fornece conteúdo de referência gerado. Ele não herda os projetos do visitante, o token de portador do aplicativo local, as credenciais do provedor ou a conexão de desktop emparelhada. Seu assistente usa trechos de documentação em vez de operar silenciosamente o espaço de trabalho CAD/CAM.

O Studio local é um processo Bun adicional porque usa bun:sqlite. Vite faz proxy de suas solicitações de API de desenvolvimento para a porta de loopback 4396. Um Cloudflare Worker implantado não pode abrir esse banco de dados local; a API de produção do Studio explica isso deliberadamente com HTTP 503.

Comandos locais

bun run --filter @cadcamfun/web start
bun run --filter @cadcamfun/web dev
bun run --filter @cadcamfun/web studio
bun test packages/web/test
bun run --filter @cadcamfun/web typecheck
bun run --filter @cadcamfun/web build

Use o Astro apenas para edição de artigos quando o Studio for desnecessário. A compilação de produção valida a geração de modelos e roteia a saída, mas não chama um back-end de modelo real, publica artefatos ou verifica uma conta Cloudflare implantada.

Geração de conteúdo e API

Os artigos vivem em src/pages/docs e compartilhe DocsLayout.astro. A barra lateral em src/data/docsSidebar.ts é o inventário da rota de documentação. docsIndex.ts adiciona resumos por rota e palavras-chave para recuperação. Uma página pública deve ter uma entrada de navegação e uma cópia de recuperação precisa; um artigo desvinculado não pode ser descoberto apenas porque seu arquivo existe.

A referência da API combina um instantâneo de contrato gerado com agrupamento de recursos selecionados em src/data/apiGroups.ts. src/lib/apiReference.ts seleciona todas as operações, resolve esquemas nomeados e fornece os modelos de recursos. O instantâneo é gerado a partir do aplicativo composto HttpApi usando sua implementação de efeito instalada.

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index
bun test test

A regeneração grava o contrato de esquema atual; ele não escreve orientações de domínio nem prova que um aplicativo remoto está na mesma versão. As páginas manuscritas explicam validação de negócios, efeitos colaterais, permissões, recuperação e limites de implementação. Mantenha essas explicações vinculadas aos manipuladores e serviços reais.

Notas de leitura da fonte podem ser preparadas em packages/web/.tmp/content. São material editorial temporário, excluído de publicação. Mova as explicações finalizadas para as páginas do artigo e atualize a navegação/recuperação; não use uma nota temporária como única documentação para uma operação.

Exportação de redução

GET /llm lista páginas de documentação conhecidas como links Markdown. Com path, ele busca o artigo renderizado correspondente e o converte em Markdown no estilo GitHub. Adicionando format=prompt agrupa esse conteúdo em um prompt de instruções que inclui sua fonte canônica.

curl "$DOCS_ORIGIN/llm"
curl "$DOCS_ORIGIN/llm?path=/docs/cam"
curl "$DOCS_ORIGIN/llm?path=/docs/api/projects&format=prompt"

O pipeline lê apenas o artigo marcado data-llm-document. Ele remove conteúdo, scripts, estilos, decoração SVG e botões excluídos para que os controles de navegação e cópia não se tornem contexto de resposta. Ele converte blocos de código, títulos, tabelas e links em vez de manter um segundo corpus Markdown manuscrito.

Somente caminhos de documentação conhecidos são admitidos. Caminhos desconhecidos retornam 404. Uma falha no carregamento da página retorna 502; outra falha de conversão retorna 500. A resposta é Markdown com CORS de leitura permissiva e uma política de cache pública de cinco minutos com obsoleto enquanto revalida. Esses artigos públicos exportados não contêm credenciais de projetos locais.

No Cloudflare, o auxiliar prefere a ligação ASSETS para páginas pré-renderizadas. Isso mantém a leitura dentro da implantação do Worker. O desenvolvimento pode voltar à busca ao vivo quando a construção de ativo existente não contém uma página. Uma árvore dist local obsoleta e uma árvore de origem atual podem, portanto, ser entradas diferentes durante a edição.

Assistente de documentação

POST /api/docs-assistant aceita mensagens de conversação, um caminho de documentação opcional e um identificador de sessão de back-end opcional. Ele mantém apenas as mensagens do usuário/assistente, corta cada mensagem para 1,200 caracteres, retém as 12 mensagens válidas mais recentes e exige uma pergunta do usuário.

A recuperação primeiro pontua a pergunta atual e as perguntas anteriores do usuário em relação a títulos, rotas, palavras-chave e resumos. A página conhecida atual é mantida. Quando uma ligação Workers AI está disponível, um planejador de chamada de ferramenta opcional pode selecionar rotas de documentação relevantes; seleções inválidas ou falhas do planejador recorrem à recuperação lexical.

Até três páginas são carregadas. Cada um é condensado em um orçamento de 5,000 caracteres, mantendo sua introdução e seções correspondentes. Uma página longa de recursos de API, portanto, não é fornecida automaticamente por completo ao modelo. Vincule o usuário à operação relevante quando o trecho não contém detalhes suficientes.

O Markdown carregado é armazenado em cache separadamente por 30 minutos quando o cache do Worker está disponível. Uma edição de origem pode exigir atualização de cache em uma implantação já em execução. Se nenhuma página selecionada puder ser carregada, a rota retornará 502. Se não existir nenhuma ligação Workers AI ou configuração completa de back-end do nikcli, ele retornará 503 antes da geração.

Uma única solicitação do assistente pode conter no máximo 12 mensagens de conversa, e uma pergunta é limitada a 1,200 caracteres (MAX_MESSAGES e MAX_QUESTION_CHARS em src/lib/docsAssistant.ts).

Modelos e limites de taxas

O caminho nikcli cria ou reutiliza uma sessão remota, assina seu fluxo antes de enviar a mensagem e aplica um tempo limite de 90 segundos. Este é o suporte à documentação em um back-end configurado; seu token é separado da ponte ou das credenciais do provedor do aplicativo CAD/CAM.

O limitador de taxa requer a ligação KV opcional e um cabeçalho IP do cliente. Sua sequência de leitura/incremento/gravação é de melhor esforço, em vez de uma cota de segurança atômica, e falhas de KV são permitidas. Sem a vinculação, não há limite por IP imposto. Não a apresente como uma alocação garantida nem confie em afirmações de preços de modelos históricos.

A configuração do adaptador local desativa ligações remotas. O modelo não tem implementação local neste site. Uma visualização normal do artigo local pode funcionar enquanto as solicitações do assistente retornam 503. Configure um back-end acessível ou valide o comportamento do modelo no ambiente de implantação pretendido.

Artefatos de guia gerados

Uma solicitação de guia, lista de verificação, referência ou página reutilizável semelhante pode produzir um rascunho de artefato. Com ARTIFACTS R2, o auxiliar o normaliza para um documento HTML e grava o conteúdo mais os metadados. Um documento vazio normalizado ou maior que 256 KiB não é publicado.

O link retornado carrega um ?key= capacidade de leitura. Qualquer pessoa com esse link completo pode ler o artefato. O identificador simples não é suficiente; não há porta de login da conta do proprietário para esses guias anônimos. Trate a chave como uma credencial de compartilhamento e evite colocar dados privados do projeto em um guia compartilhado publicamente.

O visualizador usa um shell privado e sem cache e uma sandbox iframe, permitindo scripts e pop-ups sem permissão de mesma origem. A rota HTML bruta aplica uma política de conteúdo que permite scripts/estilos embutidos e imagens de blob/dados incorporados, mas bloqueia buscas de rede externas e carregamentos de fontes/estilos/scripts externos. Os guias gerados devem ser independentes; seu layout não pode depender do DOM atual do site ou do armazenamento local.

O auxiliar de publicação atual grava a versão 1 e um novo recurso aleatório. A rota bruta pode selecionar uma versão armazenada válida com v; uma versão inválida ou fora do intervalo volta para a versão armazenada mais recente. Esse suporte de recuperação não estabelece uma API pública de edição/gerenciamento de versão.

ARTIFACT_PUBLIC_ORIGIN pode selecionar a origem do link de compartilhamento canônico para implantações não locais. O armazenamento ausente retorna 503 no acesso ao artefato. O conteúdo ausente retorna 404 e uma capacidade de leitura rejeitada retorna 401. Mantenha separados os ativos de armazenamento de guias gerados e de documentação pública.

Estúdio local

O estúdio escolhe CADCAMFUN_DB, então DATABASE_URL depois de remover um prefixo de arquivo inicial, então o repositório data/cadcamfun.db. Ele abre apenas um arquivo existente. Esta seleção difere do padrão relativo ao processo da CLI do pacote de banco de dados e do diretório de dados do aplicativo da área de trabalho nativa.

O login verifica a senha armazenada de um usuário existente com o verificador de senha do Bun. Ele grava uma sessão de sete dias na tabela Session do aplicativo e define um cookie SameSite=Lax somente HTTP para o Studio local. Nenhum registro de usuário ou inicialização de senha inicial é implementado por esse servidor local. Um perfil local nativo sem senha não adquire uma senha do Studio automaticamente.

Consultas de visão geral autenticadas contam usuários, projetos, desenhos e percursos da ferramenta na instalação selecionada e, em seguida, retornam os oito projetos atualizados mais recentemente. É uma visão geral da instalação local, em vez de um painel filtrado por propriedade por projeto. Use um banco de dados e uma conta locais apropriados; abrir o Studio não é motivo para apontá-lo para um arquivo de usuário não relacionado.

A queda na produção sob /studio/api/* é HTTP 503. A implantação dos documentos públicos não carrega o conteúdo SQLite nem transforma esta ferramenta local em um serviço de banco de dados hospedado.

Implantação

wrangler.toml declara a entrada do Worker, o diretório de ativos estáticos, os domínios personalizados em cadcam.fun, Workers AI, namespaces KV de sessão e limite de taxa de assistente e o bucket de artefato R2. O Wrangler provisiona recursos dedicados e os vincula à implantação. Configure segredos por meio do ambiente Cloudflare de destino. Um nome de ligação em uma interface TypeScript não é prova de que o recurso existe na conta.

O script de implantação constrói o Astro, escreve dist/.assetsignore portanto, a entrada Worker é excluída dos ativos estáticos e invoca a implantação do Wrangler. A implantação é uma operação de publicação; a verificação normal da documentação deve usar verificações locais e de compilação sem executá-la.

Before publishing, validate static routes and API snapshot freshness, confirm intended bindings, verify assistant failure behavior without its backend, and check artifact capability access if storage is enabled. Após a publicação, inspecione a implantação resultante e o back-end configurado em vez de tratar uma construção local como evidência de um serviço ativo.

Diagnóstico operacional

Fontes de implementação: astro.config.mjs, wrangler.toml, script/dev.ts, script/deploy.ts, script/studio-server.ts, src/lib/docsMarkdown.ts, docsRetrieval.ts, nikcliDocsSession.ts, docsArtifact.tse os manipuladores de rota em src/pages.

Scripts do pacote docs

Escrevendo uma página

1. Criar src/pages/docs/<slug>.astro usando DocsLayout com title, subtitle, description e um toc matriz cujo hrefs corresponde aos IDs da seção.
2. Escreva cada seção como <section id="…" class="doc-section"> com um <h2>.
3. Usar DocCode (language, title) para código, DocCallout (type informação, aviso ou nota) para avisos, DocCard para grades de links, DocRelated no final, e DocViewer3D para visualizações 3D.
4. Escape de colchetes literais no texto como { e }; coloque código dentro de uma expressão como {String.raw`…`}.
5. Adicione a página aos dados da barra lateral e execute bun run typecheck, que também reconstrói e verifica o índice de pesquisa.

---
export const prerender = true
import DocsLayout from "../../layouts/DocsLayout.astro"
import DocCode from "../../components/docs/DocCode.astro"
const toc = [{ title: "Overview", href: "#overview" }]
---
<DocsLayout title="Example" subtitle="One line." description="For search engines." toc={toc}>
  <section id="overview" class="doc-section">
    <h2>Overview</h2>
    <p>Text with an escaped brace: &#123;</p>
    <DocCode language="bash" title="Run">{`bun run typecheck`}</DocCode>
  </section>
</DocsLayout>

3Visualizações D

O componente usa three.js com Z up, é montado somente quando rolado para visualização e mostra um substituto de texto sem WebGL. Alimente-o com resultados reais, como movimentos do kernel, em vez de coordenadas desenhadas à mão.

Em 3D