عمليات توثيق الموقع

هندسة الموقع

packages/web هو تطبيق إخراج خادم Astro مع محول Cloudflare. تعلن المقالات التوثيقية عن العرض المسبق وتصبح أصول HTML ثابتة. تتعامل مسارات الخادم مع تصدير Markdown، وطلبات مساعد التوثيق، وعرض العناصر/المحتوى الأولي، واستوديو الإنتاج الاحتياطي. يعد هذا النشر منفصلاً عن CAD/CAM السايدكار.

يصف موقع الوثائق سلوك التطبيق والمحتوى المرجعي الذي تم إنشاؤه للمستلزمات. ولا يرث مشاريع الزائر أو الرمز المميز لحامل التطبيق المحلي أو بيانات اعتماد الموفر أو اتصال سطح المكتب المقترن. يستخدم مساعده مقتطفات من الوثائق بدلاً من تشغيل مساحة عمل CAD/CAM بصمت.

يعد الاستوديو المحلي بمثابة عملية Bun إضافية لأنه يستخدم bun:sqlite. تطلب Vite Proxys واجهة برمجة تطبيقات التطوير الخاصة بها إلى منفذ الاسترجاع 4396. لا يمكن لعامل Cloudflare الذي تم نشره فتح قاعدة البيانات المحلية تلك؛ تشرح واجهة برمجة تطبيقات Studio الإنتاج هذا الأمر عمدًا باستخدام 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

استخدم Astro وحده لتحرير المقالات عندما يكون الاستوديو غير ضروري. يتحقق تجميع الإنتاج من صحة إنشاء القالب ومخرجات المسار، لكنه لا يستدعي واجهة خلفية حقيقية للنموذج، أو ينشر عناصر، أو يتحقق من حساب Cloudflare المنشور.

إنشاء المحتوى وواجهة برمجة التطبيقات (API).

المقالات تعيش في src/pages/docs ومشاركة DocsLayout.astro. الشريط الجانبي في src/data/docsSidebar.ts هو مخزون مسار التوثيق. docsIndex.ts يضيف ملخصات لكل مسار وكلمات رئيسية لاسترجاعها. يجب أن تحتوي الصفحة العامة على مدخل تنقل ونسخة استرجاع دقيقة؛ لا تصبح المقالة غير المرتبطة قابلة للاكتشاف لمجرد وجود الملف الخاص بها.

يجمع مرجع واجهة برمجة التطبيقات (API) بين لقطة العقد التي تم إنشاؤها مع تجميع الموارد المنسقة 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 يسرد صفحات التوثيق المعروفة كروابط Markdown. مع path، فهو يجلب المقالة المقدمة المقابلة ويحولها إلى Markdown بنكهة 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. فهو يزيل المحتوى المستبعد والبرامج النصية والأنماط وزخرفة SVG والأزرار بحيث لا تصبح عناصر التحكم في التنقل والنسخ سياقًا للإجابة. يقوم بتحويل كتل التعليمات البرمجية والعناوين والجداول والروابط بدلاً من الاحتفاظ بمجموعة Markdown مكتوبة بخط اليد.

يتم قبول مسارات التوثيق المعروفة فقط. مسارات غير معروفة ترجع 404. يؤدي فشل تحميل الصفحة إلى إرجاع 502؛ فشل تحويل آخر يرجع 500. الرد هو تخفيض السعر مع السماح بقراءة CORS وسياسة التخزين المؤقت العامة لمدة خمس دقائق مع إعادة التحقق من الصحة. لا تحتوي هذه المقالات العامة المصدرة على بيانات اعتماد المشروع المحلي.

في Cloudflare، يفضل المساعد ربط ASSETS للصفحات المعروضة مسبقًا. يؤدي هذا إلى الاحتفاظ بالقراءة ضمن نشر العامل. يمكن أن يعود التطوير إلى الجلب المباشر عندما لا يحتوي إصدار الأصول الحالي على صفحة. وبالتالي يمكن أن تكون شجرة التوزيع المحلية التي لا معنى لها وشجرة المصدر الحالية مدخلات مختلفة أثناء التحرير.

مساعد التوثيق

POST /api/docs-assistant يقبل رسائل المحادثة ومسار التوثيق الاختياري ومعرف جلسة الواجهة الخلفية الاختياري. فهو يحتفظ فقط برسائل المستخدم/المساعد، ويقطع كل رسالة إلى 1،200 من الأحرف، ويحتفظ بأحدث 12 من الرسائل الصالحة، ويتطلب سؤال المستخدم.

يقوم الاسترجاع أولاً بتسجيل السؤال الحالي وأسئلة المستخدم السابقة مقابل العناوين والمسارات والكلمات الأساسية والملخصات. يتم الاحتفاظ بالصفحة المعروفة الحالية. عندما يتوفر ربط الذكاء الاصطناعي للعمال، يمكن لمخطط استدعاء الأداة الاختياري تحديد مسارات التوثيق ذات الصلة؛ التحديدات غير الصالحة أو فشل المخطط ترجع إلى الاسترجاع المعجمي.

يتم تحميل ما يصل إلى ثلاث صفحات. يتم تكثيف كل منها في ميزانية مكونة من 5،000 أحرف من خلال الاحتفاظ بالمقدمة والأقسام المطابقة. وبالتالي، لا يتم توفير صفحة موارد واجهة برمجة التطبيقات الطويلة تلقائيًا بالكامل للنموذج. قم بربط المستخدم بالعملية ذات الصلة عندما لا يحتوي المقتطف على تفاصيل كافية.

يتم تخزين Markdown المحمل مؤقتًا بشكل منفصل لمدة 30 دقيقة عندما تكون ذاكرة التخزين المؤقت للعامل متاحة. يمكن أن يتطلب تحرير المصدر تحديث ذاكرة التخزين المؤقت في عملية نشر قيد التشغيل بالفعل. إذا لم يكن من الممكن تحميل أي صفحة محددة، فسيرجع المسار 502. إذا لم يكن هناك ربط للذكاء الاصطناعي للعمال أو تكوين كامل للواجهة الخلفية لـ nikcli، فسيتم إرجاع 503 قبل الإنشاء.

قد يحمل طلب مساعد واحد على الأكثر 12 من رسائل المحادثة، ويقتصر السؤال على 1،200 حرفًا (MAX_MESSAGES و MAX_QUESTION_CHARS في src/lib/docsAssistant.ts).

النماذج وحدود المعدل

ينشئ مسار nikcli جلسة عمل عن بعد أو يعيد استخدامها، ويشترك في الدفق الخاص بها قبل إرسال الرسالة، ويطبق مهلة زمنية مدتها 90 ثانية. هذا هو دعم التوثيق على الواجهة الخلفية التي تم تكوينها؛ الرمز المميز الخاص به منفصل عن جسر تطبيق CAD/CAM أو بيانات اعتماد الموفر.

يتطلب محدد المعدل ربط KV الاختياري ورأس IP للعميل. يعد تسلسل القراءة/الزيادة/الكتابة الخاص به هو أفضل جهد بدلاً من حصة الأمان الذرية، ويُسمح بفشل KV. بدون الربط لا يوجد حد أقصى مفروض لكل IP. لا تقدمه كتخصيص مضمون أو تعتمد على مطالبات التسعير النموذجي التاريخي.

يقوم تكوين المحول المحلي بتعطيل الارتباطات البعيدة. النموذج ليس له تنفيذ محلي في هذا الموقع. يمكن أن تعمل معاينة المقالة المحلية العادية أثناء إرجاع طلبات المساعد 503. قم بتكوين واجهة خلفية يمكن الوصول إليها أو التحقق من صحة سلوك النموذج في بيئة النشر المقصودة.

التحف الدليلية التي تم إنشاؤها

يمكن أن يؤدي طلب دليل أو قائمة مرجعية أو مرجع أو صفحة مماثلة قابلة لإعادة الاستخدام إلى إنتاج مسودة أثرية. مع ARTIFACTS R2، يقوم المساعد بتطبيعه إلى مستند HTML ويكتب المحتوى بالإضافة إلى البيانات التعريفية. لم يتم نشر مستند فارغ تمت تسويته أو مستند أكبر من 256 KiB.

الرابط الذي تم إرجاعه يحمل أ ?key= القدرة على القراءة. يمكن لأي شخص لديه هذا الرابط الكامل قراءة القطعة الأثرية. المعرف المجرد ليس كافيا؛ لا توجد بوابة تسجيل دخول لحساب المالك لهذه الأدلة المجهولة. تعامل مع المفتاح باعتباره بيانات اعتماد مشاركة وتجنب وضع بيانات المشروع الخاصة في دليل مشترك بشكل عام.

يستخدم العارض غلافًا خاصًا غير مخبأ وصندوق حماية iframe يسمح بالنصوص البرمجية والنوافذ المنبثقة دون الحصول على إذن من نفس المصدر. يطبق مسار HTML الأولي سياسة محتوى تسمح بالبرامج النصية/الأنماط المضمنة وصور البيانات/البيانات الثنائية الكبيرة المضمنة ولكنها تحظر عمليات جلب الشبكة الخارجية وتحميل الخطوط/النمط/البرنامج النصي الخارجي. يجب أن تكون الأدلة التي تم إنشاؤها قائمة بذاتها؛ لا يمكن أن يعتمد تخطيطها على DOM الحالي للموقع أو التخزين المحلي.

يقوم مساعد النشر الحالي بكتابة الإصدار 1 وإمكانات عشوائية جديدة. يمكن للمسار الأولي تحديد نسخة مخزنة صالحة باستخدام v; يعود الإصدار غير الصالح أو خارج النطاق إلى أحدث إصدار مخزن. لا يؤدي دعم الاسترجاع هذا إلى إنشاء واجهة برمجة تطبيقات عامة للتحرير/إدارة الإصدار.

ARTIFACT_PUBLIC_ORIGIN يمكن تحديد أصل رابط المشاركة الأساسي لعمليات النشر غير المحلية. يؤدي التخزين المفقود إلى إرجاع 503 عند الوصول إلى العناصر. يُرجع المحتوى المفقود 404، وترجع إمكانية القراءة المرفوضة 401. احتفظ بتخزين الدليل الذي تم إنشاؤه وأصول التوثيق العام منفصلة.

الاستوديو المحلي

يختار الاستوديو CADCAMFUN_DB، ثم DATABASE_URL بعد تجريد بادئة الملف الأولية، ثم بادئة المستودع data/cadcamfun.db. يفتح فقط ملف موجود. يختلف هذا التحديد عن الإعداد الافتراضي النسبي للعملية لحزمة قاعدة البيانات ودليل بيانات التطبيق لسطح المكتب الأصلي.

يتحقق تسجيل الدخول من كلمة المرور المخزنة للمستخدم الحالي باستخدام أداة التحقق من كلمة المرور الخاصة بـ Bun. يقوم بكتابة جلسة مدتها سبعة أيام لجدول جلسة التطبيق ويقوم بتعيين ملف تعريف ارتباط HTTP فقط، SameSite=Lax للاستوديو المحلي. لا يتم تنفيذ تسجيل المستخدم أو التمهيد لكلمة المرور الأولية بواسطة هذا الخادم المحلي. لا يحصل ملف التعريف المحلي الأصلي بدون كلمة مرور على كلمة مرور الاستوديو تلقائيًا.

تقوم استعلامات النظرة العامة المصادق عليها بإحصاء المستخدمين والمشاريع والرسومات ومسارات الأدوات عبر التثبيت المحدد، ثم تقوم بإرجاع المشاريع الثمانية التي تم تحديثها مؤخرًا. إنها نظرة عامة على التثبيت المحلي وليست لوحة معلومات تمت تصفيتها حسب الملكية لكل مشروع. استخدام قاعدة بيانات وحساب محليين مناسبين؛ لا يعد فتح الاستوديو سببًا لتوجيهه إلى ملف مستخدم غير ذي صلة.

الإنتاج الاحتياطي تحت /studio/api/* هو HTTP 503. لا يؤدي نشر المستندات العامة إلى تحميل محتويات SQLite أو تحويل هذه الأداة المحلية إلى خدمة قاعدة بيانات مستضافة.

النشر

wrangler.toml يعلن عن إدخال العامل، ودليل الأصول الثابتة، والمجالات المخصصة ضمن cadcam.fun، والذكاء الاصطناعي للعمال، ومساحات أسماء KV للجلسة والمساعد، ومجموعة العناصر R2. توفر رانجلر موارد مخصصة وتربطها بالنشر. قم بتكوين الأسرار من خلال بيئة Cloudflare المستهدفة. لا يعد اسم الربط في واجهة TypeScript دليلاً على وجود المورد في الحساب.

يكتب البرنامج النصي للنشر أنه يبني أسترو dist/.assetsignore لذلك يتم استبعاد إدخال العامل من الأصول الثابتة، ويستدعي نشر Wrangler. النشر هو عملية نشر؛ يجب أن يستخدم التحقق من الوثائق العادية عمليات التحقق البناءة والمحلية دون تشغيلها.

قبل النشر، تحقق من صحة المسارات الثابتة وحداثة لقطة واجهة برمجة التطبيقات (API)، وتأكد من الارتباطات المقصودة، وتحقق من سلوك فشل المساعد دون الواجهة الخلفية الخاصة به، وتحقق من الوصول إلى إمكانية الوصول إلى العناصر إذا تم تمكين التخزين. بعد النشر، قم بفحص النشر الناتج والواجهة الخلفية التي تم تكوينها بدلاً من التعامل مع الإصدار المحلي كدليل على الخدمة المباشرة.

التشخيص التشغيلي

مصادر التنفيذ: 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 لمعاينات 3D.
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معاينات ثلاثية الأبعاد

يستخدم المكون three.js مع Z لأعلى، ويتم تثبيته فقط عند التمرير إلى العرض ويعرض نصًا احتياطيًا بدون WebGL. قم بتغذيته بمخرجات حقيقية، مثل تحركات النواة، بدلاً من الإحداثيات المرسومة يدويًا.

في 3د