شروع کار
Qbit AI Toolkit در حال حاضر بهصورت یک source repository توسعه داده میشود و مالک catalog داراییها، installerهای قابل استفاده مجدد، قراردادهای validation و سایت مستندات است.
ساختار repository
qbit-ai-toolkit/
├── catalog.json
├── schemas/
├── installers/
│ └── codex-ai-tooling/
├── agent-assets/
├── prompts/
├── libraries/
├── templates/
├── docs/
├── website/
├── tests/
└── tools/
docs/ محتوای canonical مستندات را نگه میدارد. website/ فقط برنامه Docusaurus برای render و deploy مستندات است.
توسعه مستندات
سایت با Docusaurus و Bun ساخته میشود:
cd website
bun ci
bun run start
برای اجرای locale فارسی:
bun run start:fa
دستورهای start و start:fa فقط یک locale را در حالت توسعه اجرا میکنند. برای بررسی language switcher و جابهجایی واقعی میان فارسی و انگلیسی از آنها استفاده نکنید.
برای preview کامل و مشابه production که هر دو زبان را همزمان سرو میکند:
bun run preview
در preview، نسخه انگلیسی در / و نسخه فارسی در /fa/ در دسترس است و language switcher باید میان این دو مسیر کار کند.
برای build نهایی هر دو زبان:
bun run build
سایت production برای https://ai-toolkit.qbit.click تنظیم شده و پس از رسیدن تغییرات مستندات یا website به branch main توسط GitHub Actions منتشر میشود.
اعتبارسنجی repository
قراردادهای metadata و static با دستور زیر بررسی میشوند:
python tools/validate.py
قبول شدن unit test بهتنهایی کافی نیست؛ catalog، manifest، templateها، version pinها و قواعد hygiene نیز باید با هم سازگار باشند.
فرایند Documentation-first
برای تغییر رفتار یا معماری:
- ابتدا قرارداد مطلوب و رفتار compatibility در مستندات تعریف شود.
- اگر قرارداد ماشینخوان تغییر میکند، schema یا catalog بهروزرسانی شود.
- implementation بدون ساخت source of truth دوم انجام شود.
- در لایههای لازم unit، integration و E2E تست معنادار اضافه شود.
- documentation، implementation و release metadata با هم validation شوند.
namespaceهای تاریخی installer مانند .qbit-toolkit/ و markerهای موجود بخشی از قرارداد سازگاری نسخه 1.0 هستند. تغییر نام repository به qbit-ai-toolkit به معنی rename خودکار این مسیرها نیست؛ تغییر آنها نیازمند migration صریح است.