Opérations du site de documentation

Architecture du site

packages/web est une application de sortie serveur Astro avec l'adaptateur Cloudflare. Les articles de documentation déclarent le prérendu et deviennent des actifs HTML statiques. Les routes du serveur gèrent l'exportation Markdown, les requêtes de l'assistant de documentation, l'affichage des artefacts/contenu brut et la solution de secours du Studio de production. Ce déploiement est distinct du sidecar CAO/FAO.

Le site de documentation décrit le comportement de l'application et fournit le contenu de référence généré. Il n'hérite pas des projets d'un visiteur, du jeton du porteur d'application locale, des informations d'identification du fournisseur ou de la connexion de bureau couplée. Son assistant utilise des extraits de documentation plutôt que d'exploiter silencieusement l'espace de travail CAO/FAO.

Le Studio local est un processus Bun supplémentaire car il utilise bun:sqlite. Vite transmet ses requêtes d'API de développement au port de bouclage 4396. Un Cloudflare Worker déployé ne peut pas ouvrir cette base de données locale ; l'API de production Studio explique délibérément cela avec HTTP 503.

Commandes locales

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

Utilisez Astro seul pour l'édition d'articles lorsque Studio n'est pas nécessaire. La compilation de production valide la génération de modèles et la sortie d'itinéraire, mais n'appelle pas de véritable backend de modèle, ne publie pas d'artefacts et ne vérifie pas un compte Cloudflare déployé.

Génération de contenu et d'API

Les articles vivent dans src/pages/docs et partager DocsLayout.astro. La barre latérale dans src/data/docsSidebar.ts est l'inventaire de la route de la documentation. docsIndex.ts ajoute des résumés par itinéraire et des mots-clés pour la récupération. Une page publique doit contenir à la fois une entrée de navigation et une copie de récupération précise ; un article non lié ne devient pas détectable simplement parce que son fichier existe.

La référence API combine un instantané de contrat généré avec un regroupement de ressources organisé dans src/data/apiGroups.ts. src/lib/apiReference.ts sélectionne chaque opération, résout les schémas nommés et fournit les modèles de ressources. L'instantané est généré à partir de l'application composée HttpApi à l'aide de son implémentation Effect installée.

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

La régénération rédige le contrat de schéma actuel ; il n'écrit pas de conseils de domaine et ne prouve pas qu'une application distante utilise la même version. Des pages manuscrites expliquent la validation commerciale, les effets secondaires, les autorisations, la récupération et les limites de mise en œuvre. Gardez ces explications liées aux gestionnaires et services réels.

Les notes de lecture de la source peuvent être préparées sous packages/web/.tmp/content. Il s’agit de matériel éditorial temporaire, exclu de la publication. Déplacer les explications terminées dans les pages d'articles et mettre à jour la navigation/récupération ; n’utilisez pas une note temporaire comme seule documentation pour une opération.

Exportation de démarques

GET /llm répertorie les pages de documentation connues sous forme de liens Markdown. Avec path, il récupère l'article rendu correspondant et le convertit en Markdown à saveur GitHub. Ajout format=prompt encapsule ce contenu dans une invite d'instructions qui inclut sa source canonique.

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

Le pipeline lit uniquement l'article marqué data-llm-document. Il supprime le contenu, les scripts, les styles, la décoration SVG et les boutons exclus afin que les contrôles de navigation et de copie ne deviennent pas un contexte de réponse. Il convertit les blocs de code, les en-têtes, les tableaux et les liens plutôt que de conserver un deuxième corpus Markdown manuscrit.

Seuls les chemins de documentation connus sont admis. Les chemins inconnus renvoient 404. Un échec de chargement de page renvoie 502 ; un autre échec de conversion renvoie 500. La réponse est Markdown avec un CORS de lecture permissive et une politique de cache publique de cinq minutes avec une revalidation obsolète. Ces articles publics exportés ne contiennent pas d’informations d’identification de projet local.

Sur Cloudflare, l'assistant préfère la liaison ASSETS pour les pages pré-rendues. Cela conserve la lecture dans le déploiement Worker. Le développement peut recourir à la récupération en direct lorsque la version d'actif existante ne contient pas de page. Une arborescence de distribution locale obsolète et une arborescence source actuelle peuvent donc être des entrées différentes lors de l'édition.

Assistante documentaire

POST /api/docs-assistant accepte les messages de conversation, un chemin de documentation facultatif et un identifiant de session backend facultatif. Il conserve uniquement les messages utilisateur/assistant, réduit chaque message à 1,200 caractères, conserve les 12 messages valides les plus récents et nécessite une question de l'utilisateur.

La récupération classe d'abord la question actuelle et les questions précédentes des utilisateurs par rapport aux titres, itinéraires, mots-clés et résumés. La page actuellement connue est conservée. Lorsqu'une liaison Workers AI est disponible, un planificateur d'appels d'outils facultatif peut sélectionner les itinéraires de documentation pertinents ; les sélections invalides ou les échecs du planificateur reviennent à la récupération lexicale.

Jusqu'à trois pages sont chargées. Chacun est condensé à un budget de 5,000 personnages en conservant son introduction et ses sections correspondantes. Une longue page de ressources API n'est donc pas automatiquement fournie dans son intégralité au modèle. Liez l’utilisateur à l’opération concernée lorsque l’extrait ne contient pas suffisamment de détails.

Loaded Markdown est mis en cache séparément pendant 30 minutes lorsque le cache Worker est disponible. Une modification de source peut nécessiter une actualisation du cache dans un déploiement déjà en cours d'exécution. Si aucune page sélectionnée ne peut être chargée, l'itinéraire renvoie 502. S'il n'existe aucune liaison Workers AI ou configuration backend nikcli complète, elle renvoie 503 avant la génération.

Une seule demande d'assistant peut contenir au maximum 12 messages de conversation, et une question est limitée à 1,200 caractères (MAX_MESSAGES et MAX_QUESTION_CHARS dans src/lib/docsAssistant.ts).

Modèles et limites de tarifs

Le chemin nikcli crée ou réutilise une session distante, s'abonne à son flux avant d'envoyer le message et applique un délai d'attente de 90 secondes. Il s'agit d'un support de documentation sur un backend configuré ; son jeton est distinct du pont ou des informations d'identification du fournisseur de l'application CAO/FAO.

Le limiteur de débit nécessite la liaison KV facultative et un en-tête IP client. Sa séquence de lecture/incrémentation/écriture est la meilleure possible plutôt qu'un quota de sécurité atomique, et les pannes KV sont autorisées. Sans la liaison, il n’y a pas de plafond par IP appliqué. Ne le présentez pas comme une allocation garantie et ne vous fiez pas aux allégations historiques de tarification des modèles.

La configuration de l'adaptateur local désactive les liaisons distantes. Le modèle n'a pas d'implémentation locale sur ce site. Un aperçu normal d'un article local peut fonctionner pendant que les requêtes de l'assistant renvoient 503. Configurez un backend accessible ou validez le comportement du modèle dans l'environnement de déploiement prévu.

Artefacts de guide générés

Une demande de guide, de liste de contrôle, de référence ou de page réutilisable similaire peut produire une ébauche d’artefact. Avec ARTIFACTS R2 stockage, l'assistant le normalise en un document HTML et écrit le contenu ainsi que les métadonnées. Un document vide normalisé ou supérieur à 256 KiB n'est pas publié.

Le lien renvoyé porte un ?key= capacité de lecture. Toute personne disposant de ce lien complet peut lire l'artefact. Le simple identifiant n’est pas suffisant ; il n'y a pas de porte de connexion au compte propriétaire pour ces guides anonymes. Traitez la clé comme un identifiant de partage et évitez de placer les données de projets privés dans un guide partagé publiquement.

La visionneuse utilise un shell privé non mis en cache et un bac à sable iframe autorisant les scripts et les fenêtres contextuelles sans autorisation de même origine. La route HTML brute applique une politique de contenu qui autorise les scripts/styles en ligne et les données/images blob intégrées, mais bloque les récupérations de réseau externe et les chargements de polices/styles/scripts externes. Les guides générés doivent être autonomes ; leur disposition ne peut pas dépendre du DOM actuel du site ou du stockage local.

L'assistant de publication actuel écrit la version 1 et une nouvelle fonctionnalité aléatoire. La route brute peut sélectionner une version stockée valide avec v; une version invalide ou hors plage revient à la dernière version stockée. Cette prise en charge de la récupération n'établit pas d'API publique d'édition/de gestion des versions.

ARTIFACT_PUBLIC_ORIGIN peut sélectionner l’origine canonique du lien de partage pour les déploiements non locaux. Le stockage manquant renvoie 503 lors de l'accès à l'artefact. Le contenu manquant renvoie 404 et une capacité de lecture rejetée renvoie 401. Séparez le stockage du guide généré et les ressources de documentation publique.

Studio local

L'atelier choisit CADCAMFUN_DB, alors DATABASE_URL après avoir supprimé un préfixe de fichier initial, puis le référentiel data/cadcamfun.db. Il ouvre uniquement un fichier existant. Cette sélection diffère de la valeur par défaut relative au processus de la CLI du package de base de données et du répertoire de données d'application du bureau natif.

La connexion vérifie le mot de passe stocké d'un utilisateur existant avec le vérificateur de mot de passe de Bun. Il écrit une session de sept jours dans la table Session de l'application et définit un cookie HTTP uniquement, SameSite=Lax pour le Studio local. Aucun enregistrement d'utilisateur ou amorçage par mot de passe initial n'est implémenté par ce serveur local. Un profil local natif sans mot de passe n'acquiert pas automatiquement un mot de passe Studio.

Les requêtes de présentation authentifiées comptent les utilisateurs, les projets, les dessins et les parcours d'outils dans l'installation sélectionnée, puis renvoient les huit projets les plus récemment mis à jour. Il s'agit d'un aperçu de l'installation locale plutôt que d'un tableau de bord filtré par propriété par projet. Utiliser une base de données et un compte locaux appropriés ; l'ouverture de Studio n'est pas une raison pour le pointer vers le fichier d'un utilisateur non lié.

Le repli de la production sous /studio/api/* est HTTP 503. Le déploiement des documents publics ne télécharge pas le contenu SQLite et ne transforme pas cet outil local en un service de base de données hébergé.

Déploiement

wrangler.toml déclare l'entrée Worker, le répertoire d'actifs statiques, les domaines personnalisés sous cadcam.fun, Workers AI, les espaces de noms KV de session et de limite de taux d'assistant et le compartiment d'artefacts R2. Wrangler provisionne des ressources dédiées et les lie au déploiement. Configurez les secrets via l'environnement Cloudflare cible. Un nom de liaison dans une interface TypeScript ne prouve pas que la ressource existe dans le compte.

Le script de déploiement construit Astro, écrit dist/.assetsignore ainsi, l'entrée Worker est exclue des actifs statiques et appelle le déploiement Wrangler. Le déploiement est une opération de publication ; la vérification normale de la documentation doit utiliser des vérifications de build et locales sans l'exécuter.

Avant la publication, validez les routes statiques et la fraîcheur des instantanés d'API, confirmez les liaisons prévues, vérifiez le comportement en cas d'échec de l'assistant sans son backend et vérifiez l'accès aux fonctionnalités des artefacts si le stockage est activé. Après la publication, inspectez le déploiement résultant et le backend configuré plutôt que de traiter une version locale comme la preuve d'un service en direct.

Diagnostic opérationnel

Sources de mise en œuvre : astro.config.mjs, wrangler.toml, script/dev.ts, script/deploy.ts, script/studio-server.ts, src/lib/docsMarkdown.ts, docsRetrieval.ts, nikcliDocsSession.ts, docsArtifact.ts, et les gestionnaires de route sous src/pages.

Scripts du package docs

Écrire une page

1. Créer src/pages/docs/<slug>.astro en utilisant DocsLayout avec title, subtitle, description et un toc tableau dont hrefs correspondent aux identifiants de section.
2. Écrivez chaque section comme <section id="…" class="doc-section"> avec un <h2>.
3. Utiliser DocCode (language, title) pour le code, DocCallout (type info, avertissement ou note) pour les avertissements, DocCard pour les grilles de liens, DocRelated à la fin, et DocViewer3D pour les aperçus 3D.
4. Échapper aux accolades littérales dans le texte comme { et }; mettre du code dans une expression telle que {String.raw`…`}.
5. Ajoutez la page aux données de la barre latérale et exécutez bun run typecheck, qui reconstruit et vérifie également l'index de recherche.

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

3Aperçus D

Le composant utilise three.js avec Z up, se monte uniquement lorsqu'il défile et affiche un texte de secours sans WebGL. Donnez-lui une sortie réelle, telle que les mouvements du noyau, plutôt que des coordonnées dessinées à la main.

En 3D