Operazioni del sito di documentazione

Architettura del sito

packages/web è un'applicazione di output del server Astro con l'adattatore Cloudflare. Gli articoli della documentazione dichiarano il prerendering e diventano risorse HTML statiche. I percorsi del server gestiscono l'esportazione Markdown, le richieste dell'assistente documentazione, la visualizzazione di artefatti/contenuti non elaborati e il fallback di Studio di produzione. Questa distribuzione è separata dal sidecar CAD/CAM.

Il sito della documentazione descrive il comportamento dell'applicazione e fornisce il contenuto di riferimento generato. Non eredita i progetti del visitatore, il token di connessione dell'applicazione locale, le credenziali del provider o la connessione desktop associata. Il suo assistente utilizza estratti di documentazione anziché operare silenziosamente nell'area di lavoro CAD/CAM.

Lo Studio locale è un processo Bun aggiuntivo perché utilizza bun:sqlite. Vite inoltra le proprie richieste API di sviluppo alla porta di loopback 4396. Un Cloudflare Worker distribuito non può aprire quel database locale; l'API di Production Studio lo spiega deliberatamente con HTTP 503.

Comandi locali

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

Utilizza Astro da solo per la modifica degli articoli quando Studio non è necessario. La compilazione della produzione convalida la generazione del modello e l'instradamento dell'output, ma non richiama un backend del modello reale, non pubblica artefatti né verifica un account Cloudflare distribuito.

Generazione di contenuti e API

Gli articoli vivono src/pages/docs e condividere DocsLayout.astro. La barra laterale dentro src/data/docsSidebar.ts è l'inventario del percorso della documentazione. docsIndex.ts aggiunge riepiloghi per percorso e parole chiave per il recupero. Una pagina pubblica dovrebbe avere sia una voce di navigazione che una copia di recupero accurata; un articolo scollegato non diventa rilevabile semplicemente perché il suo file esiste.

Il riferimento API combina uno snapshot del contratto generato con un raggruppamento curato di risorse src/data/apiGroups.ts. src/lib/apiReference.ts seleziona ogni operazione, risolve gli schemi denominati e fornisce i modelli di risorse. Lo snapshot viene generato dall'applicazione composta HttpApi utilizzando l'implementazione dell'effetto installata.

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

La rigenerazione scrive il contratto dello schema corrente; non scrive indicazioni sul dominio né dimostra che un'applicazione remota sia sulla stessa versione. Le pagine scritte a mano spiegano la convalida aziendale, gli effetti collaterali, le autorizzazioni, il ripristino e i limiti di implementazione. Mantieni queste spiegazioni legate ai gestori e ai servizi effettivi.

Le note per la lettura della fonte possono essere preparate sotto packages/web/.tmp/content. Sono materiale editoriale temporaneo, escluso dalla pubblicazione. Spostare le spiegazioni completate nelle pagine degli articoli e aggiornare la navigazione/recupero; non utilizzare una nota temporanea come unica documentazione di un'operazione.

Esportazione con ribasso

GET /llm elenca le pagine di documentazione conosciute come collegamenti Markdown. Con path, recupera l'articolo visualizzato corrispondente e lo converte in Markdown basato su GitHub. Aggiunta format=prompt racchiude quel contenuto in un prompt di istruzioni che include la sua fonte canonica.

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

La pipeline legge solo l'articolo contrassegnato data-llm-document. Rimuove i contenuti, gli script, gli stili, le decorazioni SVG e i pulsanti esclusi in modo che i controlli di navigazione e copia non diventino il contesto della risposta. Converte blocchi di codice, intestazioni, tabelle e collegamenti anziché mantenere un secondo corpus Markdown scritto a mano.

Sono ammessi solo percorsi di documentazione conosciuti. I percorsi sconosciuti restituiscono 404. Un errore di caricamento della pagina restituisce 502; un altro errore di conversione restituisce 500. La risposta è Markdown con CORS in lettura permissiva e una policy di cache pubblica di cinque minuti con stale- while-revalidate. Questi articoli pubblici esportati non contengono le credenziali del progetto locale.

Su Cloudflare, l'helper preferisce l'associazione ASSETS per le pagine prerenderizzate. Ciò mantiene la lettura all'interno della distribuzione Worker. Lo sviluppo può ricorrere al recupero in tempo reale quando la build dell'asset esistente non contiene una pagina. Un albero dist locale obsoleto e un albero di origine corrente possono quindi essere input diversi durante la modifica.

Assistente alla documentazione

POST /api/docs-assistant accetta messaggi di conversazione, un percorso di documentazione facoltativo e un identificatore di sessione backend facoltativo. Conserva solo i messaggi dell'utente/assistente, ritaglia ciascun messaggio in 1,200 caratteri, conserva i messaggi validi 12 più recenti e richiede una domanda dell'utente.

Il recupero valuta innanzitutto la domanda corrente e le domande precedenti dell'utente rispetto a titoli, percorsi, parole chiave e riepiloghi. La pagina attualmente conosciuta viene mantenuta. Quando è disponibile un'associazione Workers AI, un pianificatore di chiamate agli strumenti opzionale può selezionare i percorsi di documentazione pertinenti; selezioni non valide o fallimenti del pianificatore ricadono nel recupero lessicale.

Vengono caricate fino a tre pagine. Ciascuno è ridotto a un budget di 5,000 caratteri mantenendo la sua introduzione e le sezioni corrispondenti. Una lunga pagina di risorse API pertanto non viene fornita automaticamente per intero al modello. Collega l'utente all'operazione rilevante quando l'estratto non contiene dettagli sufficienti.

Il Markdown caricato viene memorizzato nella cache separatamente per 30 minuti quando la cache di lavoro è disponibile. Una modifica dell'origine può richiedere l'aggiornamento della cache in una distribuzione già in esecuzione. Se non è possibile caricare alcuna pagina selezionata, il percorso restituisce 502. Se non esiste alcun collegamento AI Workers o una configurazione backend nikcli completa, restituisce 503 prima della generazione.

Una singola richiesta dell'assistente può contenere al massimo 12 messaggi di conversazione e una domanda è limitata a 1,200 caratteri (MAX_MESSAGES e MAX_QUESTION_CHARS in src/lib/docsAssistant.ts).

Modelli e limiti tariffari

Il percorso nikcli crea o riutilizza una sessione remota, si iscrive al suo flusso prima di inviare il messaggio e applica un timeout di turno di 90 secondi. Questo è il supporto della documentazione su un backend configurato; il suo token è separato dal bridge dell'applicazione CAD/CAM o dalle credenziali del fornitore.

Il limitatore di velocità richiede l'associazione KV opzionale e un'intestazione IP del client. La sua sequenza di lettura/incremento/scrittura è basata sul massimo sforzo piuttosto che su una quota di sicurezza atomica e gli errori KV sono consentiti. Senza l'associazione non viene applicato alcun limite per IP. Non presentarlo come un'allocazione garantita né fare affidamento su affermazioni sui prezzi del modello storico.

La configurazione dell'adattatore locale disabilita i collegamenti remoti. Il modello non ha un'implementazione locale in questo sito. Una normale anteprima di un articolo locale può funzionare mentre le richieste dell'assistente restituiscono 503. Configura un backend raggiungibile o convalida il comportamento del modello nell'ambiente di distribuzione previsto.

Artefatti guida generati

Una richiesta di guida, lista di controllo, riferimento o pagina riutilizzabile simile può produrre una bozza di artefatto. Con ARTIFACTS R2 storage, l'helper lo normalizza in un documento HTML e scrive il contenuto più i metadati. Un documento vuoto normalizzato o uno più grande di 256 KiB non viene pubblicato.

Il collegamento restituito porta a ?key= capacità di lettura. Chiunque abbia quel collegamento completo può leggere l'artefatto. Il semplice identificatore non è sufficiente; non esiste una porta di accesso all'account proprietario per queste guide anonime. Tratta la chiave come una credenziale di condivisione ed evita di inserire i dati del progetto privato in una guida condivisa pubblicamente.

Il visualizzatore utilizza una shell privata, senza cache e un sandbox iframe che consente script e popup senza autorizzazione della stessa origine. Il percorso HTML non elaborato applica una policy di contenuto che consente script/stili in linea e immagini di dati/blob incorporati ma blocca i recuperi dalla rete esterna e i caricamenti di caratteri/stili/script esterni. Le guide generate devono essere autonome; il loro layout non può dipendere dal DOM corrente del sito o dalla memoria locale.

L'attuale assistente per la pubblicazione scrive la versione 1 e una nuova funzionalità casuale. Il percorso grezzo può selezionare una versione memorizzata valida con v; una versione non valida o fuori range torna all'ultima versione memorizzata. Tale supporto per il recupero non stabilisce un'API pubblica di modifica/gestione della versione.

ARTIFACT_PUBLIC_ORIGIN può selezionare l'origine canonica del collegamento di condivisione per le distribuzioni non locali. Lo spazio di archiviazione mancante restituisce 503 sull'accesso agli artefatti. Il contenuto mancante restituisce 404 e una capacità di lettura rifiutata restituisce 401. Mantieni separati l'archiviazione della guida generata e le risorse della documentazione pubblica.

Studio locale

Lo Studio sceglie CADCAMFUN_DB, poi DATABASE_URL dopo aver rimosso il prefisso del file iniziale, quindi quello del repository data/cadcamfun.db. Apre solo un file esistente. Questa selezione differisce dall'impostazione predefinita relativa al processo della CLI del pacchetto DB e dalla directory dei dati dell'applicazione del desktop nativo.

L'accesso controlla la password memorizzata di un utente esistente con il verificatore password di Bun. Scrive una sessione di sette giorni nella tabella Session dell'applicazione e imposta un cookie SameSite=Lax solo HTTP per lo Studio locale. Il server locale non implementa alcuna registrazione dell'utente o bootstrap della password iniziale. Un profilo locale nativo senza password non acquisisce automaticamente una password di Studio.

Le query di panoramica autenticate contano utenti, progetti, disegni e percorsi utensile nell'installazione selezionata, quindi restituiscono gli otto progetti aggiornati più recentemente. Si tratta di una panoramica dell'installazione locale anziché di un dashboard filtrato in base alla proprietà del progetto. Utilizzare un database e un account locali appropriati; aprire Studio non è un motivo per indirizzarlo al file di un utente non correlato.

La produzione fallback under /studio/api/* è HTTP 503. La distribuzione dei documenti pubblici non carica i contenuti SQLite né trasforma questo strumento locale in un servizio di database ospitato.

Distribuzione

wrangler.toml dichiara la voce Worker, la directory delle risorse statiche, i domini personalizzati in cadcam.fun, Workers AI, gli spazi dei nomi KV con limite di velocità di sessione e assistente e il bucket di artefatti R2. Wrangler fornisce risorse dedicate e le vincola alla distribuzione. Configura i segreti attraverso l'ambiente Cloudflare di destinazione. Un nome di associazione in un'interfaccia TypeScript non è una prova dell'esistenza della risorsa nell'account.

Lo script di distribuzione crea Astro, scrive dist/.assetsignore quindi la voce Worker è esclusa dalle risorse statiche e richiama la distribuzione di Wrangler. La distribuzione è un'operazione di pubblicazione; la normale verifica della documentazione dovrebbe utilizzare controlli build e locali senza eseguirla.

Prima della pubblicazione, convalida le route statiche e l'aggiornamento degli snapshot API, conferma le associazioni previste, verifica il comportamento degli errori dell'assistente senza il relativo backend e controlla l'accesso alle funzionalità degli artefatti se l'archiviazione è abilitata. Dopo la pubblicazione, ispeziona la distribuzione risultante e il backend configurato anziché considerare una build locale come prova di un servizio live.

Diagnosi operativa

Fonti di implementazione: 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 i gestori del percorso sotto src/pages.

Script del pacchetto docs

Scrivere una pagina

1. Creare src/pages/docs/<slug>.astro utilizzando DocsLayout con title, subtitle, description e un toc array di cui hrefs corrisponde agli ID delle sezioni.
2. Scrivi ogni sezione come <section id="…" class="doc-section"> con uno <h2>.
3. Utilizzo DocCode (language, title) per il codice, DocCallout (type info, avvisa o nota) per avvisi, DocCard per le griglie di collegamento, DocRelated alla fine, e DocViewer3D per le anteprime 3D.
4. Escape le parentesi graffe letterali nel testo come { e }; inserisci il codice all'interno di un'espressione come {String.raw`…`}.
5. Aggiungi la pagina ai dati della barra laterale ed esegui bun run typecheck, che ricostruisce e controlla anche l'indice di ricerca.

---
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>

3Anteprime D

Il componente utilizza three.js con Z up, si monta solo quando si scorre nella vista e mostra un fallback di testo senza WebGL. Forniscigli output reali, come gli spostamenti del kernel, piuttosto che coordinate disegnate a mano.

Nel 3D