Betrieb der Dokumentationsstelle

Site-Architektur

packages/web ist eine Astro-Server-Ausgabeanwendung mit dem Cloudflare-Adapter. Dokumentationsartikel deklarieren das Vorrendern und werden zu statischen HTML-Assets. Serverrouten kümmern sich um den Markdown-Export, Anforderungen des Dokumentationsassistenten, die Anzeige von Artefakten/Rohinhalten und den Produktions-Studio-Fallback. Diese Bereitstellung ist vom CAD/CAM-Sidecar getrennt.

Die Dokumentationsseite beschreibt das Anwendungsverhalten und stellt generierte Referenzinhalte bereit. Es erbt nicht die Projekte eines Besuchers, das Inhaber-Token der lokalen Anwendung, die Anmeldeinformationen des Anbieters oder die gekoppelte Desktop-Verbindung. Sein Assistent verwendet Dokumentationsauszüge, anstatt den CAD/CAM-Arbeitsbereich stillschweigend zu bedienen.

Das lokale Studio ist ein zusätzlicher Bun-Prozess, da es verwendet wird bun:sqlite. Vite leitet seine Entwicklungs-API-Anfragen per Proxy an den Loopback-Port 4396 weiter. Ein bereitgestellter Cloudflare-Worker kann diese lokale Datenbank nicht öffnen; Die Production Studio API erklärt dies bewusst mit HTTP 503.

Lokale Befehle

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

Verwenden Sie Astro allein für die Artikelbearbeitung, wenn Studio nicht erforderlich ist. Die Produktionskompilierung validiert die Vorlagengenerierung und leitet die Ausgabe weiter, ruft jedoch kein echtes Modell-Backend auf, veröffentlicht keine Artefakte und überprüft kein bereitgestelltes Cloudflare-Konto.

Inhalts- und API-Generierung

Artikel leben in src/pages/docs und teilen DocsLayout.astro. Die Seitenleiste in src/data/docsSidebar.ts ist das Dokumentationsrouteninventar. docsIndex.ts fügt Zusammenfassungen und Schlüsselwörter pro Route zum Abrufen hinzu. Eine öffentliche Seite sollte sowohl einen Navigationseintrag als auch eine genaue Abrufkopie enthalten; Ein nicht verlinkter Artikel wird nicht allein deshalb auffindbar, weil seine Datei vorhanden ist.

Die API-Referenz kombiniert einen generierten Vertrags-Snapshot mit einer kuratierten Ressourcengruppierung src/data/apiGroups.ts. src/lib/apiReference.ts wählt jede Operation aus, löst benannte Schemata auf und stellt die Ressourcenvorlagen bereit. Der Snapshot wird aus der zusammengesetzten Anwendung HttpApi mithilfe der installierten Effect-Implementierung generiert.

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

Die Regeneration schreibt den aktuellen Schemavertrag; Es werden keine Domänenanweisungen geschrieben oder nachgewiesen, dass eine Remoteanwendung dieselbe Version hat. Auf handgeschriebenen Seiten werden Geschäftsvalidierung, Nebenwirkungen, Berechtigungen, Wiederherstellung und Implementierungsgrenzen erläutert. Halten Sie diese Erklärungen an die tatsächlichen Abwickler und Dienste gebunden.

Hinweise zur Quellenlektüre können unter erstellt werden packages/web/.tmp/content. Es handelt sich um temporäres redaktionelles Material, das von der Veröffentlichung ausgeschlossen ist. Fertige Erklärungen in Artikelseiten verschieben und Navigation/Abruf aktualisieren; Verwenden Sie eine temporäre Notiz nicht als einzige Dokumentation für eine Operation.

Markdown-Export

GET /llm lists known documentation pages as Markdown links. Mit path, ruft es den entsprechenden gerenderten Artikel ab und konvertiert ihn in Markdown im GitHub-Stil. Hinzufügen format=prompt verpackt diesen Inhalt in eine Anweisungsaufforderung, die seine kanonische Quelle enthält.

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

Die Pipeline liest nur den markierten Artikel data-llm-document. Es entfernt ausgeschlossene Inhalte, Skripte, Stile, SVG-Dekorationen und Schaltflächen, sodass Navigations- und Kopiersteuerelemente nicht zum Antwortkontext werden. Es konvertiert Codeblöcke, Überschriften, Tabellen und Links, anstatt ein zweites handgeschriebenes Markdown-Korpus zu verwalten.

Es sind nur bekannte Dokumentationspfade zugelassen. Unbekannte Pfade geben 404 zurück. Ein Fehler beim Laden der Seite gibt 502 zurück; Ein weiterer Konvertierungsfehler gibt 500 zurück. Die Antwort ist Markdown mit permissivem Lese-CORS und einer öffentlichen Fünf-Minuten-Cache-Richtlinie mit Stale-While-Revalidate. Diese exportierten öffentlichen Artikel enthalten keine lokalen Projektanmeldeinformationen.

Auf Cloudflare bevorzugt der Helfer die ASSETS-Bindung für vorgerenderte Seiten. Dadurch bleibt der Lesevorgang innerhalb der Worker-Bereitstellung. Die Entwicklung kann auf Live-Abruf zurückgreifen, wenn der vorhandene Asset-Build keine Seite enthält. Ein veralteter lokaler Dist-Baum und ein aktueller Quellbaum können daher beim Bearbeiten unterschiedliche Eingaben sein.

Dokumentationsassistent

POST /api/docs-assistant akzeptiert Konversationsnachrichten, einen optionalen Dokumentationspfad und eine optionale Backend-Sitzungskennung. Es speichert nur Benutzer-/Assistentennachrichten, kürzt jede Nachricht auf 1,200 Zeichen, behält die neuesten 12 gültigen Nachrichten bei und erfordert eine Benutzerfrage.

Beim Abrufen werden zunächst die aktuelle Frage und frühere Benutzerfragen anhand von Titeln, Routen, Schlüsselwörtern und Zusammenfassungen bewertet. Die aktuell bekannte Seite bleibt erhalten. Wenn eine Workers AI-Anbindung verfügbar ist, kann ein optionaler Tool-Call-Planer relevante Dokumentationsrouten auswählen; Ungültige Auswahlen oder Planfehler fallen auf den lexikalischen Abruf zurück.

Es werden bis zu drei Seiten geladen. Jedes wird auf ein 5,000-Zeichen-Budget komprimiert, indem die Einleitungs- und Matching-Abschnitte beibehalten werden. Eine lange API-Ressourcenseite wird dem Modell daher nicht automatisch vollständig zur Verfügung gestellt. Verknüpfen Sie den Benutzer mit dem entsprechenden Vorgang, wenn der Auszug nicht genügend Details enthält.

Geladener Markdown wird 30 Minuten lang separat zwischengespeichert, wenn der Worker-Cache verfügbar ist. Eine Quellbearbeitung kann eine Cache-Aktualisierung in einer bereits ausgeführten Bereitstellung erfordern. Wenn keine ausgewählte Seite geladen werden kann, gibt die Route 502 zurück. Wenn keine Workers AI-Bindung oder vollständige Nikcli-Backend-Konfiguration vorhanden ist, wird vor der Generierung 503 zurückgegeben.

Eine einzelne Assistentenanfrage kann höchstens 12 Konversationsnachrichten enthalten und eine Frage ist auf 1,200 Zeichen beschränkt (MAX_MESSAGES und MAX_QUESTION_CHARS in src/lib/docsAssistant.ts).

Modelle und Tarifgrenzen

Der Nikcli-Pfad erstellt eine Remote-Sitzung oder verwendet sie wieder, abonniert ihren Stream vor dem Senden der Nachricht und wendet ein Turn-Timeout von 90 Sekunden an. Dies ist Dokumentationsunterstützung auf einem konfigurierten Backend; Sein Token ist von den Bridge- oder Provider-Anmeldeinformationen der CAD/CAM-Anwendung getrennt.

Der Ratenbegrenzer erfordert die optionale KV-Bindung und einen Client-IP-Header. Seine Lese-/Inkrementierungs-/Schreibsequenz ist eine Best-Effort-Sequenz und keine atomare Sicherheitsquote, und KV-Fehler werden durchgelassen. Ohne die Bindung gibt es keine erzwungene Obergrenze pro IP. Stellen Sie es nicht als garantierte Zuteilung dar und verlassen Sie sich nicht auf historische Modellpreisaussagen.

Die lokale Adapterkonfiguration deaktiviert Remotebindungen. Das Modell hat auf dieser Site keine lokale Implementierung. Eine normale lokale Artikelvorschau kann funktionieren, während Assistentenanfragen 503 zurückgeben. Konfigurieren Sie ein erreichbares Backend oder validieren Sie das Modellverhalten in der vorgesehenen Bereitstellungsumgebung.

Generierte Leitartefakte

Eine Anfrage nach einem Leitfaden, einer Checkliste, einer Referenz oder einer ähnlichen wiederverwendbaren Seite kann zu einem Artefaktentwurf führen. Mit ARTIFACTS R2-Speicherung, der Helfer normalisiert es in ein HTML-Dokument und schreibt Inhalt und Metadaten. Ein normalisiertes leeres Dokument oder ein Dokument, das größer als 256 KiB ist, wird nicht veröffentlicht.

Der zurückgegebene Link trägt a ?key= lesefähigkeit. Jeder mit diesem vollständigen Link kann das Artefakt lesen. Die bloße Kennung reicht nicht aus; Für diese anonymen Guides gibt es kein Login-Gate für das Eigentümerkonto. Behandeln Sie den Schlüssel als Freigabeberechtigung und vermeiden Sie es, private Projektdaten in einem öffentlich freigegebenen Leitfaden abzulegen.

Der Viewer verwendet eine private, nicht zwischengespeicherte Shell und eine Iframe-Sandbox, die Skripte und Popups ohne Same-Origin-Berechtigung ermöglicht. Die Roh-HTML-Route wendet eine Inhaltsrichtlinie an, die Inline-Skripte/-Stile und eingebettete Daten/Blob-Bilder zulässt, aber externe Netzwerkabrufe und externe Schriftarten/Stile/Skript-Ladevorgänge blockiert. Generierte Leitfäden müssen eigenständig sein; Ihr Layout darf nicht vom aktuellen DOM oder lokalen Speicher der Site abhängen.

Der aktuelle Veröffentlichungshelfer schreibt Version 1 und eine neue Zufallsfunktion. Die Rohroute kann mit eine gültige gespeicherte Version auswählen v; bei einer ungültigen oder außerhalb des zulässigen Bereichs liegenden Version wird auf die neueste gespeicherte Version zurückgegriffen. Diese Abrufunterstützung richtet keine öffentliche Bearbeitungs-/Versionsverwaltungs-API ein.

ARTIFACT_PUBLIC_ORIGIN sie können den kanonischen Share-Link-Ursprung für nicht lokale Bereitstellungen auswählen. Fehlender Speicher gibt 503 beim Artefaktzugriff zurück. Fehlender Inhalt gibt 404 zurück und eine abgelehnte Lesefunktion gibt 401 zurück. Halten Sie die Speicherung generierter Anleitungen und die öffentliche Dokumentation getrennt.

Lokales Studio

Studio wählt CADCAMFUN_DB, dann DATABASE_URL nach dem Entfernen eines anfänglichen Dateipräfixes folgt das des Repositorys data/cadcamfun.db. Es öffnet nur eine vorhandene Datei. Diese Auswahl unterscheidet sich von der prozessbezogenen Standardeinstellung der DB-Paket-CLI und dem Anwendungsdatenverzeichnis des nativen Desktops.

Bei der Anmeldung wird das gespeicherte Passwort eines bestehenden Benutzers mit dem Passwortprüfer von Bun überprüft. Es schreibt eine siebentägige Sitzung in die Sitzungstabelle der Anwendung und legt ein reines HTTP-Cookie „SameSite=Lax“ für das lokale Studio fest. Auf diesem lokalen Server ist weder eine Benutzerregistrierung noch ein Initialpasswort-Bootstrap implementiert. Ein natives lokales Profil ohne Passwort erhält nicht automatisch ein Studio-Passwort.

Authentifizierte Übersichtsabfragen zählen Benutzer, Projekte, Zeichnungen und Werkzeugwege in der ausgewählten Installation und geben dann die acht zuletzt aktualisierten Projekte zurück. Es handelt sich um eine lokale Installationsübersicht und nicht um ein Dashboard, das nach Eigentumsrechten für jedes Projekt gefiltert wird. Verwenden Sie eine geeignete lokale Datenbank und ein entsprechendes Konto. Das Öffnen von Studio ist kein Grund, es auf die Datei eines nicht verwandten Benutzers zu verweisen.

Der Produktionsfallback unter /studio/api/* ist HTTP 503. Durch die Bereitstellung der öffentlichen Dokumente werden keine SQLite-Inhalte hochgeladen und dieses lokale Tool nicht in einen gehosteten Datenbankdienst umgewandelt.

Einsatz

wrangler.toml deklariert den Worker-Eintrag, das statische Asset-Verzeichnis, benutzerdefinierte Domänen unter cadcam.fun, Workers AI, Session- und Assistant-Rate-Limit-KV-Namespaces und den R2-Artefakt-Bucket. Wrangler stellt dedizierte Ressourcen bereit und bindet sie an die Bereitstellung. Konfigurieren Sie Geheimnisse über die Cloudflare-Zielumgebung. Ein Bindungsname in einer TypeScript-Schnittstelle ist kein Beweis dafür, dass die Ressource im Konto vorhanden ist.

Das Deploy-Skript erstellt Astro, schreibt dist/.assetsignore daher wird der Worker-Eintrag von statischen Assets ausgeschlossen und ruft die Wrangler-Bereitstellung auf. Die Bereitstellung ist ein Veröffentlichungsvorgang. Die normale Dokumentationsüberprüfung sollte Build- und lokale Prüfungen verwenden, ohne sie auszuführen.

Überprüfen Sie vor der Veröffentlichung statische Routen und die Aktualität von API-Snapshots, bestätigen Sie beabsichtigte Bindungen, überprüfen Sie das Fehlerverhalten des Assistenten ohne sein Backend und prüfen Sie den Zugriff auf Artefaktfunktionen, wenn der Speicher aktiviert ist. Überprüfen Sie nach der Veröffentlichung die resultierende Bereitstellung und das konfigurierte Backend, anstatt einen lokalen Build als Beweis für einen Live-Dienst zu betrachten.

Betriebsdiagnose

Implementierungsquellen: 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, und die Routenhandler unten src/pages.

Skripte des docs-Pakets

Eine Seite schreiben

1. Erstellen src/pages/docs/<slug>.astro verwenden DocsLayout mit title, subtitle, description und a toc array, dessen hrefs stimmen mit Abschnitts-IDs überein.
2. Schreiben Sie jeden Abschnitt als <section id="…" class="doc-section"> mit einem <h2>.
3. Verwenden DocCode (language, title) für Code, DocCallout (type info, Warnung oder Hinweis) für Warnungen, DocCard für Linkgitter, DocRelated am Ende, und DocViewer3D für 3D-Vorschauen.
4. Escape-Wortklammern im Text als { und }; fügen Sie Code in einen Ausdruck ein, z {String.raw`…`}.
5. Fügen Sie die Seite zu den Seitenleistendaten hinzu und führen Sie sie aus bun run typecheck, wodurch auch der Suchindex neu erstellt und überprüft wird.

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

3D-Vorschauen

Die Komponente verwendet three.js mit Z nach oben, wird nur beim Scrollen in die Ansicht gemountet und zeigt einen Text-Fallback ohne WebGL an. Füttere es mit echter Ausgabe, wie z. B. Kernelbewegungen, statt mit handgezeichneten Koordinaten.

In 3D