दस्तावेज़ीकरण साइट संचालन

साइट वास्तुकला

packages/web क्लाउडफ्लेयर एडाप्टर के साथ एक एस्ट्रो सर्वर-आउटपुट एप्लिकेशन है। दस्तावेज़ीकरण लेख प्रीरेंडरिंग की घोषणा करते हैं और स्थिर HTML संपत्ति बन जाते हैं। सर्वर रूट मार्कडाउन निर्यात, दस्तावेज़ीकरण सहायक अनुरोध, आर्टिफैक्ट देखने/कच्ची सामग्री और उत्पादन स्टूडियो फ़ॉलबैक को संभालते हैं। यह परिनियोजन CAD/CAM साइडकार से अलग है।

दस्तावेज़ीकरण साइट एप्लिकेशन व्यवहार का वर्णन करती है और उत्पन्न संदर्भ सामग्री प्रदान करती है। यह किसी विज़िटर के प्रोजेक्ट, स्थानीय एप्लिकेशन बियरर टोकन, प्रदाता क्रेडेंशियल या युग्मित डेस्कटॉप कनेक्शन को इनहेरिट नहीं करता है। इसका सहायक सीएडी/सीएएम कार्यक्षेत्र को चुपचाप संचालित करने के बजाय दस्तावेज़ीकरण अंशों का उपयोग करता है।

स्थानीय स्टूडियो एक अतिरिक्त Bun प्रक्रिया है क्योंकि यह इसका उपयोग करता है bun:sqlite. Vite अपने विकास API अनुरोधों को लूपबैक पोर्ट 4396 पर प्रॉक्सी करता है। एक तैनात क्लाउडफ्लेयर वर्कर उस स्थानीय डेटाबेस को नहीं खोल सकता है; प्रोडक्शन स्टूडियो एपीआई जानबूझकर इसे HTTP 503 के साथ समझाता है।

स्थानीय आदेश

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

जब स्टूडियो अनावश्यक हो तो लेख संपादन के लिए अकेले एस्ट्रो का उपयोग करें। उत्पादन संकलन टेम्प्लेट जेनरेशन और रूट आउटपुट को मान्य करता है लेकिन वास्तविक मॉडल बैकएंड को कॉल नहीं करता है, कलाकृतियों को प्रकाशित नहीं करता है, या तैनात क्लाउडफ़ेयर खाते को सत्यापित नहीं करता है।

सामग्री और एपीआई पीढ़ी

लेख रहते हैं src/pages/docs और शेयर करें DocsLayout.astro. साइडबार में src/data/docsSidebar.ts दस्तावेज़ीकरण मार्ग सूची है. docsIndex.ts पुनर्प्राप्ति के लिए प्रति-मार्ग सारांश और कीवर्ड जोड़ता है। एक सार्वजनिक पृष्ठ में नेविगेशन प्रविष्टि और सटीक पुनर्प्राप्ति प्रतिलिपि दोनों होनी चाहिए; एक अनलिंक किया गया आलेख केवल इसलिए खोजने योग्य नहीं हो जाता क्योंकि उसकी फ़ाइल मौजूद है।

एपीआई संदर्भ क्यूरेटेड संसाधन समूहन के साथ एक उत्पन्न अनुबंध स्नैपशॉट को जोड़ता है src/data/apiGroups.ts. src/lib/apiReference.ts प्रत्येक ऑपरेशन का चयन करता है, नामित स्कीमा को हल करता है, और संसाधन टेम्पलेट प्रदान करता है। स्नैपशॉट इसके स्थापित प्रभाव कार्यान्वयन का उपयोग करके संकलित एप्लिकेशन HttpApi से उत्पन्न होता है।

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

पुनर्जनन वर्तमान स्कीमा अनुबंध लिखता है; यह डोमेन मार्गदर्शन नहीं लिखता या यह साबित नहीं करता कि कोई दूरस्थ एप्लिकेशन उसी संस्करण पर है। हस्तलिखित पृष्ठ व्यवसाय सत्यापन, दुष्प्रभाव, अनुमतियाँ, पुनर्प्राप्ति और कार्यान्वयन सीमाओं की व्याख्या करते हैं। उन स्पष्टीकरणों को वास्तविक संचालकों और सेवाओं से जोड़कर रखें।

सोर्स-रीडिंग नोट्स के तहत तैयार किया जा सकता है packages/web/.tmp/content. वे अस्थायी संपादकीय सामग्री हैं, जिन्हें प्रकाशन से बाहर रखा गया है। तैयार स्पष्टीकरणों को लेख पृष्ठों में ले जाएँ और नेविगेशन/पुनर्प्राप्ति को अद्यतन करें; किसी ऑपरेशन के लिए एकमात्र दस्तावेज़ के रूप में अस्थायी नोट का उपयोग न करें।

मार्कडाउन निर्यात

GET /llm ज्ञात दस्तावेज़ीकरण पृष्ठों को मार्कडाउन लिंक के रूप में सूचीबद्ध करता है। साथ path, यह संबंधित प्रस्तुत लेख को लाता है और इसे GitHub-फ्लेवर्ड मार्कडाउन में परिवर्तित करता है। जोड़ा जा रहा है format=prompt उस सामग्री को एक निर्देश प्रॉम्प्ट में लपेटता है जिसमें उसका विहित स्रोत शामिल होता है।

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

पाइपलाइन केवल चिह्नित आलेख को पढ़ती है data-llm-document. यह बहिष्कृत सामग्री, स्क्रिप्ट, शैलियों, एसवीजी सजावट और बटन को हटा देता है ताकि नेविगेशन और कॉपी नियंत्रण उत्तर संदर्भ न बनें। यह दूसरे हस्तलिखित मार्कडाउन कॉर्पस को बनाए रखने के बजाय कोड ब्लॉक, हेडिंग, टेबल और लिंक को परिवर्तित करता है।

केवल ज्ञात दस्तावेज़ीकरण पथ ही स्वीकार किए जाते हैं। अज्ञात पथ 404 लौटते हैं। पृष्ठ-लोडिंग विफलता 502 लौटाती है; एक अन्य रूपांतरण विफलता रिटर्न 500 देती है। प्रतिक्रिया अनुज्ञेय पढ़ने वाले CORS के साथ मार्कडाउन और बासी-जबकि-पुनर्वैधीकरण के साथ सार्वजनिक पांच मिनट की कैश नीति है। इन निर्यातित सार्वजनिक लेखों में स्थानीय परियोजना क्रेडेंशियल शामिल नहीं हैं।

क्लाउडफ़ेयर पर, सहायक पहले से रेंडर किए गए पृष्ठों के लिए ASSETS बाइंडिंग को प्राथमिकता देता है। यह रीड को वर्कर परिनियोजन के भीतर रखता है। जब मौजूदा परिसंपत्ति निर्माण में कोई पृष्ठ नहीं होता है तो विकास लाइव फ़ेचिंग पर वापस आ सकता है। इसलिए संपादन करते समय एक पुराना स्थानीय डिस्ट ट्री और एक वर्तमान स्रोत ट्री अलग-अलग इनपुट हो सकते हैं।

दस्तावेज़ीकरण सहायक

POST /api/docs-assistant वार्तालाप संदेश, एक वैकल्पिक दस्तावेज़ीकरण पथ और एक वैकल्पिक बैकएंड सत्र पहचानकर्ता स्वीकार करता है। यह केवल उपयोगकर्ता/सहायक संदेशों को रखता है, प्रत्येक संदेश को 1, 200 वर्णों में काट देता है, नवीनतम 12 वैध संदेशों को बरकरार रखता है, और उपयोगकर्ता के प्रश्न की आवश्यकता होती है।

पुनर्प्राप्ति पहले वर्तमान प्रश्न और पहले के उपयोगकर्ता प्रश्नों को शीर्षक, मार्ग, कीवर्ड और सारांश के विरुद्ध स्कोर करती है। वर्तमान ज्ञात पृष्ठ बरकरार रखा गया है. जब वर्कर्स एआई बाइंडिंग उपलब्ध होती है, तो एक वैकल्पिक टूल-कॉल प्लानर प्रासंगिक दस्तावेज़ीकरण मार्गों का चयन कर सकता है; अमान्य चयन या योजनाकार विफलताएं शाब्दिक पुनर्प्राप्ति पर वापस आती हैं।

अधिकतम तीन पृष्ठ लोड किए गए हैं. प्रत्येक को उसके परिचय और मिलान वाले अनुभागों को बनाए रखते हुए एक 5,000-वर्ण बजट में संघनित किया गया है। इसलिए एक लंबा एपीआई संसाधन पृष्ठ स्वचालित रूप से मॉडल को पूर्ण रूप से आपूर्ति नहीं किया जाता है। जब अंश में पर्याप्त विवरण न हो तो उपयोगकर्ता को संबंधित ऑपरेशन से लिंक करें।

वर्कर कैश उपलब्ध होने पर लोडेड मार्कडाउन को 30 मिनट के लिए अलग से कैश किया जाता है। किसी स्रोत संपादन के लिए पहले से चल रहे परिनियोजन में कैश रीफ़्रेश की आवश्यकता हो सकती है। यदि कोई चयनित पृष्ठ लोड नहीं किया जा सकता है, तो रूट 502 लौटाता है। यदि कोई वर्कर्स एआई बाइंडिंग या पूर्ण निक्ली बैकएंड कॉन्फ़िगरेशन मौजूद नहीं है, तो यह जेनरेशन से पहले 503 लौटाता है।

एक एकल सहायक अनुरोध में अधिकतम 12 वार्तालाप संदेश हो सकते हैं, और एक प्रश्न 1,200 वर्णों तक सीमित है (MAX_MESSAGES और MAX_QUESTION_CHARS में src/lib/docsAssistant.ts).

मॉडल और दर सीमाएँ

निक्ली पथ एक दूरस्थ सत्र बनाता है या पुन: उपयोग करता है, संदेश भेजने से पहले इसकी स्ट्रीम की सदस्यता लेता है, और एक 90-सेकंड टर्न टाइमआउट लागू करता है। यह कॉन्फ़िगर किए गए बैकएंड पर दस्तावेज़ीकरण समर्थन है; इसका टोकन CAD/CAM एप्लिकेशन के ब्रिज या प्रदाता क्रेडेंशियल से अलग है।

दर सीमक के लिए वैकल्पिक केवी बाइंडिंग और क्लाइंट आईपी हेडर की आवश्यकता होती है। इसका पढ़ना/वृद्धि/लिखना अनुक्रम परमाणु सुरक्षा कोटा के बजाय सर्वोत्तम प्रयास है, और केवी विफलताओं की अनुमति है। बंधन के बिना प्रति-आईपी सीमा लागू नहीं होती। इसे गारंटीशुदा आवंटन के रूप में प्रस्तुत न करें या ऐतिहासिक मॉडल मूल्य निर्धारण दावों पर भरोसा न करें।

स्थानीय एडाप्टर कॉन्फ़िगरेशन दूरस्थ बाइंडिंग को अक्षम कर देता है। इस साइट पर मॉडल का कोई स्थानीय कार्यान्वयन नहीं है। एक सामान्य स्थानीय लेख पूर्वावलोकन तब काम कर सकता है जब सहायक अनुरोध 503 लौटाता है। इच्छित परिनियोजन परिवेश में पहुंच योग्य बैकएंड कॉन्फ़िगर करें या मॉडल व्यवहार सत्यापित करें।

उत्पन्न गाइड कलाकृतियाँ

एक गाइड, चेकलिस्ट, संदर्भ, या इसी तरह के पुन: प्रयोज्य पृष्ठ के लिए अनुरोध एक आर्टिफैक्ट ड्राफ्ट तैयार कर सकता है। साथ ARTIFACTS आर2 भंडारण, सहायक इसे HTML दस्तावेज़ में सामान्यीकृत करता है और सामग्री प्लस मेटाडेटा लिखता है। सामान्यीकृत खाली दस्तावेज़ या 256 KiB से बड़ा दस्तावेज़ प्रकाशित नहीं किया जाता है।

लौटाए गए लिंक में एक है ?key= पढ़ने की क्षमता. वह संपूर्ण लिंक वाला कोई भी व्यक्ति कलाकृति को पढ़ सकता है। नंगे पहचानकर्ता पर्याप्त नहीं है; इन अनाम गाइडों के लिए कोई स्वामी-खाता लॉगिन गेट नहीं है। कुंजी को शेयर क्रेडेंशियल के रूप में मानें और निजी प्रोजेक्ट डेटा को सार्वजनिक रूप से साझा गाइड में डालने से बचें।

दर्शक एक निजी, गैर-कैश्ड शेल और एक आईफ्रेम सैंडबॉक्स का उपयोग करता है जो समान-मूल अनुमति के बिना स्क्रिप्ट और पॉपअप की अनुमति देता है। कच्चा HTML मार्ग एक सामग्री नीति लागू करता है जो इनलाइन स्क्रिप्ट/शैलियों और एम्बेडेड डेटा/ब्लॉब छवियों की अनुमति देता है लेकिन बाहरी नेटवर्क फ़ेच और बाहरी फ़ॉन्ट/शैली/स्क्रिप्ट लोड को रोकता है। उत्पन्न मार्गदर्शिकाएँ स्व-निहित होनी चाहिए; उनका लेआउट साइट के वर्तमान DOM या स्थानीय संग्रहण पर निर्भर नहीं हो सकता।

वर्तमान प्रकाशन सहायक संस्करण 1 और एक नई यादृच्छिक क्षमता लिखता है। कच्चा मार्ग एक वैध संग्रहीत संस्करण का चयन कर सकता है v; अमान्य या सीमा से बाहर का संस्करण नवीनतम संग्रहीत संस्करण पर वापस आ जाता है। वह पुनर्प्राप्ति समर्थन सार्वजनिक संपादन/संस्करण-प्रबंधन एपीआई स्थापित नहीं करता है।

ARTIFACT_PUBLIC_ORIGIN गैर-स्थानीय परिनियोजन के लिए कैनोनिकल शेयर-लिंक मूल का चयन कर सकते हैं। अनुपलब्ध संग्रहण आर्टिफैक्ट एक्सेस पर 503 लौटाता है। गुम सामग्री 404 लौटाती है, और अस्वीकृत पढ़ने की क्षमता 401 लौटाती है। उत्पन्न गाइड भंडारण और सार्वजनिक दस्तावेज़ीकरण परिसंपत्तियों को अलग रखें।

स्थानीय स्टूडियो

स्टूडियो चुनता है CADCAMFUN_DB, तब DATABASE_URL प्रारंभिक फ़ाइल उपसर्ग को हटाने के बाद, फिर रिपॉजिटरी को data/cadcamfun.db. यह केवल मौजूदा फ़ाइल को खोलता है। यह चयन डीबी पैकेज सीएलआई की प्रक्रिया-सापेक्ष डिफ़ॉल्ट और मूल डेस्कटॉप के एप्लिकेशन डेटा निर्देशिका से भिन्न है।

लॉगिन Bun के पासवर्ड सत्यापनकर्ता के साथ मौजूदा उपयोगकर्ता के संग्रहीत पासवर्ड की जांच करता है। यह एप्लिकेशन सत्र तालिका में सात-दिवसीय सत्र लिखता है और स्थानीय स्टूडियो के लिए HTTP-केवल, सेमसाइट=लैक्स कुकी सेट करता है। उस स्थानीय सर्वर द्वारा कोई उपयोगकर्ता-पंजीकरण या प्रारंभिक-पासवर्ड बूटस्ट्रैप कार्यान्वित नहीं किया जाता है। पासवर्ड के बिना एक मूल स्थानीय प्रोफ़ाइल स्वचालित रूप से स्टूडियो पासवर्ड प्राप्त नहीं करती है।

प्रमाणित अवलोकन क्वेरीज़ चयनित इंस्टॉलेशन में उपयोगकर्ताओं, प्रोजेक्ट्स, ड्रॉइंग और टूलपाथ की गणना करती हैं, फिर आठ सबसे हाल ही में अपडेट किए गए प्रोजेक्ट लौटाती हैं। यह प्रति-प्रोजेक्ट स्वामित्व-फ़िल्टर किए गए डैशबोर्ड के बजाय एक स्थानीय इंस्टॉलेशन अवलोकन है। एक उपयुक्त स्थानीय डेटाबेस और खाते का उपयोग करें; स्टूडियो खोलना किसी असंबंधित उपयोगकर्ता की फ़ाइल पर इंगित करने का कोई कारण नहीं है।

उत्पादन फ़ॉलबैक के अंतर्गत /studio/api/* hTTP 503 है. सार्वजनिक दस्तावेज़ों को तैनात करने से SQLite सामग्री अपलोड नहीं होती है या इस स्थानीय टूल को होस्ट की गई डेटाबेस सेवा में नहीं बदला जाता है।

तैनाती

wrangler.toml वर्कर एंट्री, स्टैटिक एसेट डायरेक्टरी, कैडकैम.फन के तहत कस्टम डोमेन, वर्कर्स एआई, सेशन और असिस्टेंट-रेट-लिमिट केवी नेमस्पेस और आर 2 आर्टिफैक्ट बकेट की घोषणा करता है। रैंगलर समर्पित संसाधनों का प्रावधान करता है और उन्हें तैनाती से बांधता है। लक्ष्य क्लाउडफ्लेयर वातावरण के माध्यम से रहस्यों को कॉन्फ़िगर करें। टाइपस्क्रिप्ट इंटरफ़ेस में बाइंडिंग नाम इस बात का प्रमाण नहीं है कि खाते में संसाधन मौजूद है।

परिनियोजन स्क्रिप्ट एस्ट्रो बनाती है, लिखती है dist/.assetsignore इसलिए वर्कर प्रविष्टि को स्थिर परिसंपत्तियों से बाहर रखा गया है, और रैंगलर परिनियोजन को आमंत्रित करता है। परिनियोजन एक प्रकाशन कार्य है; सामान्य दस्तावेज़ीकरण सत्यापन को इसे चलाए बिना बिल्ड और स्थानीय जांच का उपयोग करना चाहिए।

प्रकाशन से पहले, स्थैतिक मार्गों और एपीआई स्नैपशॉट ताजगी को मान्य करें, इच्छित बाइंडिंग की पुष्टि करें, इसके बैकएंड के बिना सहायक विफलता व्यवहार को सत्यापित करें, और भंडारण सक्षम होने पर आर्टिफैक्ट क्षमता पहुंच की जांच करें। प्रकाशन के बाद, किसी स्थानीय बिल्ड को लाइव सेवा के प्रमाण के रूप में मानने के बजाय परिणामी परिनियोजन और कॉन्फ़िगर किए गए बैकएंड का निरीक्षण करें।

परिचालन निदान

कार्यान्वयन स्रोत: 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, और रूट हैंडलर नीचे src/pages.

दस्तावेज़ पैकेज की स्क्रिप्ट

एक पेज लिखना

1. बनाएं src/pages/docs/<slug>.astro का उपयोग करते हुए DocsLayout साथ title, subtitle, description और ए toc सरणी किसकी hrefअनुभाग आईडी से मेल खाता है।
2. प्रत्येक अनुभाग को इस प्रकार लिखें <section id="…" class="doc-section"> एक के साथ <h2>.
3. उपयोग DocCode (language, title) कोड के लिए, DocCallout (type चेतावनियों के लिए जानकारी, चेतावनी या नोट), DocCard लिंक ग्रिड के लिए, DocRelated अंत में, और DocViewer3D 3डी पूर्वावलोकन के लिए।
4. पाठ में शाब्दिक ब्रेसिज़ से बचें { और }; किसी अभिव्यक्ति के अंदर कोड डालें जैसे कि {String.raw`…`}.
5. पेज को साइडबार डेटा में जोड़ें और चलाएँ bun run typecheck, जो खोज सूचकांक का पुनर्निर्माण और जाँच भी करता है।

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

3डी पूर्वावलोकन

घटक Z up के साथ three.js का उपयोग करता है, केवल दृश्य में स्क्रॉल करने पर ही माउंट होता है और WebGL के बिना टेक्स्ट फ़ॉलबैक दिखाता है। इसे हाथ से बनाए गए निर्देशांक के बजाय वास्तविक आउटपुट, जैसे कर्नेल चाल, खिलाएं।

3डी में