diff --git a/.gitignore b/.gitignore index 74a84e7..6ffe14c 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,6 @@ REFACTORING_PLAN.md REFACTORING_REPORT.md docs/.vitepress/.temp/* .temp/* +.vitepress/cache/* +.vitepress/cache/* +docs/archived-components.md diff --git a/.husky/pre-push b/.husky/pre-push new file mode 100755 index 0000000..9824d5b --- /dev/null +++ b/.husky/pre-push @@ -0,0 +1,19 @@ +#!/bin/sh +. "$(dirname "$0")/_/husky.sh" + +echo "🚀 Pre-push checks started..." +echo "" + +echo "1️⃣ Running forced build..." +if ! npm run build:force > /dev/null 2>&1; then + echo "" + echo "❌ Forced build failed! Please fix build errors before pushing." + echo "" + echo "💡 Run 'npm run build:force' to see detailed errors" + echo "💡 To skip pre-push checks: git push --no-verify" + exit 1 +fi +echo "✅ Forced build: Success" +echo "" + +echo "✅ Pre-push checks passed!" diff --git a/README.md b/README.md index 2f29c7a..1d3e4c1 100644 --- a/README.md +++ b/README.md @@ -31,16 +31,19 @@

- 简体中文 + 简体中文 繁體中文 English 日本語 Español Français + Klingon 한국어 العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

diff --git a/docs-readme/ar-SA/README.md b/docs-readme/ar-SA/README.md index 7097a59..0b8c962 100644 --- a/docs-readme/ar-SA/README.md +++ b/docs-readme/ar-SA/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _من الصفر، تعلم قائم على المشاريع، بناء أول منتج ذكاء اصطناعي لك_ +# Easy-Vibe : تعلم Vibe Coding من 0 إلى 1

- 📌 ابدأ القراءة أونلاين (Start Reading Online) + 📌 القراءة عبر الإنترنت (Read Online) · ✨ دليل تفاعلي

- اقرأ أونلاين · - خريطة التعلم · + القراءة عبر الإنترنت · + خريطة التعلم · المجتمع

@@ -39,196 +37,41 @@ 日本語 Español Français + Klingon 한국어 - العربية + العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

+ + + + + +
+ +
+ خريطة تعلم حصرية للمبتدئين +
+ توجيه من الصفر، تخطيط مسار واضح، وداعًا لـ "تعلم وانسى" + 		+ +
+ دليل مصور خطوة بخطوة +
+ شرح مفصل بالصور، كأن لديك معلمًا خاصًا بجانبك +
-## 🚀 مقدمة المشروع +في عصر الذكاء الاصطناعي، الأشخاص الذين يحولون الأفكار إلى منتجات هم غالبًا ليسوا الأقوى تقنيًا، بل هم الذين يتخذون الخطوة الأولى. **ولد Easy-Vibe لهذا الغرض.** سنأخذ بيدك من كتابة أول سطر كود إلى فهم منطق الواجهة الأمامية والخلفية، وأخيرًا إطلاق منتجك على الإنترنت. -عندما تحاول كتابة الكود بالذكاء الاصطناعي، وتواجه أخطاء مستمرة، وتريد الاستسلام غالبًا، ومن غير الواضح كيفية نشر برامجك فعليًا على الإنترنت 😢 +| المرحلة | المهارات الأساسية | المخرجات | +| ------------ | -------------------------------- | ----------------------------------------- | +| **المرحلة 1** | مقدمة في برمجة الذكاء الاصطناعي، فكر المنتج | ألعاب صغيرة تفاعلية، نماذج أولية (مبتدئ و PM) | +| **المرحلة 2** | تطوير Full-stack، تكامل الذكاء الاصطناعي، قواعد البيانات | تطبيق ذكاء اصطناعي متكامل | +| **المرحلة 3** | مهارات Claude Code المتقدمة، تطبيقات الموبايل | تطبيقات متعددة المنصات بمستوى الإنتاج | -هذا البرنامج التعليمي مصمم خصيصًا ليأخذك من 0 إلى 1، وإتقان تقنيات Vibe Coding تدريجيًا: - -- **المرحلة 1**: **من الألعاب المصغرة إلى نماذج الويب**، إتقان أساسيات برمجة الذكاء الاصطناعي وتفكير المنتج -- **المرحلة 2**: تعلم **تطوير الواجهة الأمامية/الخلفية وقدرات الذكاء الاصطناعي** المتعلقة بتقنيات Vibe Coding، إكمال تطبيق كامل -- **المرحلة 3**: إتقان بناء **التطبيقات المعقدة متعددة المنصات**، نحو تطبيقات مستوى الإنتاج - -نؤمن بأن من خلال إتقان Vibe Coding ودمجه مع التدريب المنهجي، يمكن لشخص واحد أن يصبح مطورًا يجمع بين تطوير الواجهة الأمامية، وتطوير الواجهة الخلفية، ودمج قدرات الذكاء الاصطناعي، وتصميم المنتجات. - -> **هذا المشروع موجه بشكل رئيسي إلى ثلاثة أنواع من المتعلمين:** -> -> - **المبتدئون (أشخاص عاديون / المنتج والعمليات)**: مساعدة المتعلمين غير التقنيين على فهم المفاهيم الرئيسية وإكمال أول نموذج أولي للمنتج -> - **المطورون مستوى المبتدئ-المتوسط (الطلاب والمطورون مع أساس معين)**: إتقان معرفة Vibe Coding للواجهة الأمامية/الخلفية وقدرات الذكاء الاصطناعي -> - **المطورون المتقدمون (الشركات والشركات الناشئة، مفتوحة المصدر والمطورون المستقلون)**: تقنيات التطوير المتقدمة، التطوير متعدد المنصات - -### 📖 تنقل المحتوى - -
- Learning Map -
- -### الملحق العام - -[قاموس قدرات الذكاء الاصطناعي: المفاهيم الأساسية الشائعة للذكاء الاصطناعي والمصطلحات والشروحات السيناريوية](docs/appendix/ai-capability-dictionary.md) - -### 1. مدخل للمبتدئين ونموذج المنتج - -| الفصل | المحتوى الرئيسي | الحالة | -| :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------- | :----- | -| [المقدمة: خريطة التعلم](docs/stage-0/0.1-learning-map/index.md) | دليل مسار التعلم الشامل | ✅ | -| [المبتدئ 1: عصر الذكاء الاصطناعي، إذا كنت تستطيع التحدث يمكنك البرمجة](docs/stage-0/0.2-ai-capabilities-through-games/index.md) | تجربة قدرات البرمجة بالذكاء الاصطناعي لأول مرة من خلال حالات مثل Snake | ✅ | -| [المبتدئ 2: معرفة أدوات IDE الذكاء الاصطناعي](docs/stage-1/1.1-introduction-to-ai-ide/index.md) | تعلم استخدام IDE، إنشاء ألعاب مصغرة محليًا | ✅ | -| [المبتدئ 3: بناء نموذج أولي بنفسك](docs/stage-1/1.2-building-prototype/index.md) | تحليل المتطلبات، توليد صفحة واحدة بالذكاء الاصطناعي، حتى توليد نماذج منتجات متعددة الصفحات | ✅ | -| [المبتدئ 4: إضافة قدرات الذكاء الاصطناعي إلى النموذج الأولي](docs/stage-1/1.3-integrating-ai-capabilities/index.md) | تعلم توصيل القدرات الشائعة للذكاء الاصطناعي (النص، الصورة، الفيديو) | ✅ | -| [المبتدئ 5: مشروع كامل عملي](docs/stage-1/1.4-complete-project-practice/index.md) | محاكاة سيناريوهات حقيقية، قبول ملاحظات المستخدمين للتحسين، إكمال المشروع | ✅ | -| [المشروع الكبير: إنشاء نموذج أولي كامل لتطبيق الويب وعرضه](docs/stage-1/1.5-final-project/index.md) | تنفيذ التطبيق بالكامل، عرض آثار التطبيق | ✅ | - -#### الملاحق: التفكير التجاري - -| الفصل | المحتوى الرئيسي | الحالة | -| :--------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | :----- | -| [الملحق A: التفكير في المنتج وتصميم الحل](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | أطر التفكير اللازمة لبناء منتج من الصفر إلى واحد | ✅ | -| [الملحق B: مرجع سيناريوهات تطبيق الذكاء الاصطناعي في الصناعة (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | فهم تطبيقات الذكاء الاصطناعي في مختلف الصناعات | ✅ | -| [الملحق C: مرجع إلهام سيناريوهات استهلاك الذكاء الاصطناعي (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | استكشاف تطبيقات الذكاء الاصطناعي في منتجات المستهلكين | ✅ | - -#### الملاحق: الحلول التقنية - -| الفصل | المحتوى الرئيسي | الحالة | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | :----- | -| [الملحق D: ماذا تفعل عند مواجهة أخطاء أثناء كتابة الكود](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | الأخطاء الشائعة في Vibe Coding وطرق استكشاف الأخطاء | ✅ | -| [الملحق E: مقارنة 7 أدوات برمجة الذكاء الاصطناعي](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | مقارنة واختبار منصات برمجة الذكاء الاصطناعي الرئيسية | ✅ | -| [الملحق F: تصميم مواقع الويب باستخدام وكلاء التصميم والبرمجة](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | تعلم كيفية استخدام وكلاء الذكاء الاصطناعي بشكل تعاوني | ✅ | - -### 2. مهندس تطوير مستوى المبتدئ-المتوسط - -#### قسم الواجهة الأمامية - -| الفصل | المحتوى الرئيسي | الحالة | -| :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :----- | -| [الواجهة الأمامية 0: استخدام lovart لتوليد الأصول](docs/stage-2/frontend/2.0-lovart-assets/) | استخدام lovart لتوليد الأصول المرئية مثل الشخصيات والمشاهد دفعة واحدة، توفير أساس الأصول لتصميم الواجهة وتطوير الواجهة الأمامية | 🚧 | -| [الواجهة الأمامية 1: مقدمة إلى Figma و MasterGo](docs/stage-2/frontend/2.1-figma-mastergo/) | استخدام أدوات التصميم لتنظيم هيكل المعلومات وهيكل الصفحة، وإعداد الأساس لتنفيذ الواجهة الأمامية | 🚧 | -| [الواجهة الأمامية 2: بناء أول تطبيق حديث - تصميم الواجهة](docs/stage-2/frontend/2.2-ui-design/) | إكمال واجهة قائمة على المكونات بناءً على التصاميم، تحقيق المسار الأول من التصميم إلى الكود | 🚧 | -| [الواجهة الأمامية 3: مرجع مواصفات تصميم الواجهة وتصميم واجهة متعدد المنتجات](docs/stage-2/frontend/2.3-multi-product-ui/) | توسيع واجهات متعددة المنتجات حول بصري رئيسي موحد، ممارسة قدرات التصميم المنهجي | 🚧 | -| [الواجهة الأمامية 4: لنصنع صور هوجورتس معًا](docs/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | إنشاء تطبيق واجهة أمامية بقدرات ذكاء اصطناعي مدمجة من 0 إلى 1، ربط التصميم والتطوير | ✅ | - -#### قسم الواجهة الخلفية والكامل - -| الفصل | المحتوى الرئيسي | الحالة | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :----- | -| [الواجهة الخلفية 1: ما هي API](docs/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | فهم واجهات HTTP ونماذج الطلب-الاستجابة، الاستعداد للتكامل الخلفي والتنسيق | ✅ | -| [الواجهة الخلفية 2: من قواعد البيانات إلى Supabase](docs/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) : تنفيذ قواعد البيانات وواجهات API على Supabase، ربط نماذج البيانات بصفحات الواجهة الأمامية | ✅ | -| [الواجهة الخلفية 3: LLM المساعدة في كتابة كود الواجهة والتوثيق](docs/stage-2/backend/2.3-ai-interface-code/) : استخدام LLM للمساعدة في توليد التوثيق والكود للواجهات وقواعد البيانات، تحقيق خلفي قابل للقراءة والاختبار | 🚧 | -| [الواجهة الخلفية 4: سير عمل Git](docs/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) : إدارة الكود في سير عمل Git، إجراء التحكم في الإصدار والتعاون | ✅ | -| [الواجهة الخلفية 5: نشر Zeabur](docs/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) : نشر التطبيق على Zeabur لجعله أونلاين | ✅ | -| [الواجهة الخلفية 6: أدوات تطوير CLI حديثة](docs/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) : استخدام أدوات برمجة الذكاء الاصطناعي من نوع CLI لتسريع التطوير وتصحيح الأخطاء، تشكيل سير عمل هندسي شخصي | ✅ | -| [الواجهة الخلفية 7: كيفية دمج أنظمة الدفع مثل Stripe](docs/stage-2/backend/2.7-stripe-payment/) : توصيل أنظمة الدفع، إكمال تدفق الدفع وعملية التسوية الأساسية | 🚧 | -| [المشروع الكبير 1: بناء أول تطبيق حديث - تطبيق كامل](docs/stage-2/assignments/2.1-fullstack-app/) : دمج الواجهة الأمامية والواجهة الخلفية ووحدات الدفع، إكمال تطبيق ويب كامل جاهز للإنتاج | 🚧 | -| [المشروع الكبير 2: مكتبة مكونات الواجهة الأمامية الحديثة + Trae عملية](docs/stage-2/assignments/2.2-modern-frontend-trae/) : استخدام مكتبة مكونات الواجهة الأمامية الحديثة و Trae، إكمال منتج بشكل مستقل مع تسجيل/دعم الدفع | 🚧 | - -#### ملحق قدرات الذكاء الاصطناعي - -| الفصل | المحتوى الرئيسي | الحالة | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------- | :----- | -| [الذكاء الاصطناعي 1: مقدمة إلى Dify ودمج قاعدة المعرفة](docs/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) : استخدام Dify Workflow و RAG الأساسي لبناء منتجات نوع الأدوات، إنشاء مثال لترقيات التطبيقات المستقبلية | ✅ | -| [الذكاء الاصطناعي 2: تعلم البحث في قاموس الذكاء الاصطناعي ودمج واجهات API متعددة الوسائط](docs/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) : تعلم البحث عن نماذج وواجهات API مناسبة، دمج القدرات متعددة الوسائط مثل النص والصورة في المنتجات | 🚧 | - -### 3. مهندس تطوير متقدم - -| الفصل | المحتوى الرئيسي | الحالة | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :----- | -| [المتقدم 1: MCP ومهارات ClaudeCode](docs/stage-3/core-skills/3.1-mcp-claude-code-skills/) : توسيع قدرات IDE من خلال MCP والمهارات، توصيل الخدمات الخارجية كأدوات | 🚧 | -| [المتقدم 2: كيفية جعل Coding Tools تعمل لفترة طويلة](docs/stage-3/core-skills/3.2-long-running-tasks/) : تصميم وتكوين المهام طويلة التشغيل، جعل Coding Tools أكثر استقرارًا وموثوقية | 🚧 | -| [المتقدم 3: التطوير متعدد المنصات: كيفية بناء برامج WeChat المصغرة](docs/stage-3/cross-platform/3.3-wechat-miniprogram/) : فهم نظام البرامج المصغرة WeChat، إكمال برنامج مصغر للواجهة الأمامية من القالب الرسمي إلى الإطلاق | ✅ | -| [المتقدم 4: التطوير متعدد المنصات: كيفية بناء برامج WeChat المصغرة - بما في ذلك الخلفية](docs/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) : دمج قاعدة البيانات ومنطق الواجهة الخلفية في البرامج المصغرة، تحقيق دورة نشاط كاملة | 🚧 | -| [المتقدم 5: التطوير متعدد المنصات: كيفية بناء تطبيقات Android](docs/stage-3/cross-platform/3.5-android-app/) : استخدام أدوات مثل Expo، إكمال تطوير تطبيقات Android المتكاملة للويب/الأصلي | 🚧 | -| [المتقدم 6: التطوير متعدد المنصات: كيفية بناء تطبيقات iOS](docs/stage-3/cross-platform/3.6-ios-app/) : استخدام أدوات مثل Expo، إكمال تطوير تطبيقات iOS المتكاملة للويب/الأصلي | 🚧 | -| [المتقدم 7: كيفية بناء موقعك الشخصي ومブログ الأكاديمي](docs/stage-3/personal-brand/3.7-personal-website-blog/) : من الاختيار، البناء إلى النشر، بناء صفحة رئيسية أونلاين طويلة الأجل تعرض المشاريع الشخصية والنتائج الأكاديمية | 🚧 | - -#### ملحق قدرات الذكاء الاصطناعي - -| الفصل | المحتوى الرئيسي | الحالة | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------- | :----- | -| [الذكاء الاصطناعي المتقدم 1: ما هو RAG وكيف يعمل](docs/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) : الفهم المنهجي لمبادئ RAG والهياكل الشائعة، توفير أساس استرجاع المعرفة للتطبيقات المعقدة | ✅ | -| [الذكاء الاصطناعي المتقدم 2: RAG متوسط-متقدم وتنظيف سير العمل: مثال LangGraph](docs/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) : استخدام أدوات مثل LangGraph لتصميم سير العمل متعدد الخطوات وأنظمة RAG متوسطة-متقدمة | 🚧 | - -## 🛠️ كيفية التعلم - -- وفقًا لقدراتك الشخصية، اقرأ ومارس الفصول ذات الصلة بشكل انتقائي، إذا كان لديك أسئلة اطرحها في Issues. - -## 💻 بدء هذا الدرس محليًا - -### الطريقة الحديثة - -في مربع حوار IDE الذكاء الاصطناعي (vscode، cursor، trae، etc.)، أدخل الموجه التالي لبدء هذا الدرس: - -``` -الرجاء مساعدتي في تشغيل الخدمة المحلية لهذا المشروع -``` - -### الطريقة القديمة - -1. npm install -2. npm run dev -3. افتح متصفحك وزر `http://localhost:3000` للعرض. - -## 🤝 المساهمة - -- إذا اكتشفت مشاكل، أو تعتقد أن هناك طرقًا لتحسين هذا المشروع، يمكنك تقديم Issue لإعطاء ملاحظات. إذا لم يرد أحد بعد التقديم، يمكنك الاتصال [فريق الرعاية](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) للمتابعة~ -- إذا كنت ترغب في المساهمة في هذا المشروع، يمكنك تقديم Pull Request، إذا لم يرد أحد بعد التقديم، يمكنك الاتصال [فريق الرعاية](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) للمتابعة~ -- إذا كنت مهتمًا جدًا بـ Datawhale وترغب في بدء مشروع جديد، يرجى اتباع [دليل المشاريع المفتوحة المصدر Datawhale](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)~ - -## 🙏 شكرًا لكل المساهمين - -- [散步-قائد المشروع](https://github.com/sanbuphy) (عضو Datawhale) -- Fang Ke-المعلم Tutor (عضو Datawhale، جامعة تسينغهوا) -- [Yerim Kang](https://github.com/yerim25)（جزء المشاريع العملية-جامعة تسينغهوا） -- Zhao Zhilin（جزء المشاريع العملية-جامعة تسينغهوا） -- [Li Yixuan](https://yixuan20.github.io/)（تصميم الفن الصفحة-جامعة تسينغهوا） -- جميع الزملاء في مجموعة اختبار بيتا AI Vibe Coding 101 الذين قدموا اقتراحات وخبرة - -### شكر خاص - -- شكرًا لـ [@Sm1les](https://github.com/Sm1les) على مساعدتهم ودعمهم لهذا المشروع -- شكرًا لجميع المطورين الذين ساهموا في هذا المشروع ❤️ - -
- - - -
- -## 📧 اتصل بنا - -
-

إذا كان لديك أسئلة أو اقتراحات أو شكاوى، أو ترغب في التواصل، يرجى مسح رمز QR أدناه

- - - - - -
- -## 📄 الترخيص - -
- - المشاع الإبداعي - -
-هذا العمل مرخص تحت - - المشاع الإبداعي Attribution - غير تجاري - المشاركة بالمثل 4.0 الدولي - -
- -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=datawhalechina/easy-vibe&type=date&legend=top-left)](https://www.star-history.com/#datawhalechina/easy-vibe&type=date&legend=top-left) +*(راجع التفاصيل في الوثائق عبر الإنترنت أو المستودع الرئيسي)* diff --git a/docs-readme/de-DE/README.md b/docs-readme/de-DE/README.md index ae49a81..2d3d1c2 100644 --- a/docs-readme/de-DE/README.md +++ b/docs-readme/de-DE/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _Von Null, projektbasiertes Lernen, dein erstes KI-Produkt bauen_ +# Easy-Vibe : Lerne Vibe Coding von 0 auf 1

- 📌 Online lesen starten (Start Reading Online) + 📌 Online lesen (Read Online) · ✨ Interaktives Tutorial

Online lesen · - Lernkarte · + Lernkarte · Community

@@ -39,195 +37,49 @@ 日本語 Español Français + Klingon 한국어 العربية + Türkçe Tiếng_Việt - Deutsch + Deutsch + বাংলা

+ + + + + +
+ +
+ Exklusive Lernkarte für Anfänger +
+ Anleitung ohne Vorkenntnisse, klare Pfadplanung, Schluss mit "Lernen und Vergessen" + 		+ +
+ Schritt-für-Schritt-Grafik-Tutorial +
+ Detaillierte Erklärungen, als hätte man einen Privatlehrer an der Seite +
-## 🚀 Projektvorstellung +Im Zeitalter der KI sind diejenigen, die Ideen in Produkte verwandeln, oft nicht die technisch stärksten, sondern diejenigen, die den ersten Schritt tun. **Easy-Vibe wurde dafür geschaffen.** Wir nehmen dich an die Hand, vom Schreiben deiner ersten Zeile Code bis zum Verständnis der Front-End- und Back-End-Logik und schließlich zum Start deines Produkts. -Wenn du versuchst, mit KI Code zu schreiben, ständig auf Fehler stößt, oft aufgeben möchtest und unklar ist, wie man Programme tatsächlich online bringt 😢. +- **Zielgruppe**: Anfänger, Produktmanager, Front-End / Back-End / Full-Stack Entwickler +- **Themen**: KI-Programmierung, Full-Stack-Webentwicklung, KI-Agenten, Workflows und RAG-Systeme -Dieses Tutorial ist speziell dafür konzipiert, dich von 0 auf 1 zu bringen und Vibe Coding-Techniken schrittweise zu meistern: +--- -- **Stufe 1**: **Von Mini-Spielen zu Web-Prototypen**, Beherrschung von KI-Programmiergrundlagen und Produktdenken -- **Stufe 2**: Lernen von **Frontend/Backend-Entwicklung und KI-Fähigkeiten** im Zusammenhang mit Vibe Coding-Techniken, Vervollständigung einer kompletten Anwendung -- **Stufe 3**: Beherrschung des Baus von **plattformübergreifenden komplexen Anwendungen**, hin zu produktionsreifen Anwendungen +Easy-Vibe führt dich in drei Phasen von 0 auf 1: -Wir glauben, dass durch die Beherrschung von Vibe Coding in Kombination mit systematischem Training eine einzelne Person zu einem Entwickler werden kann, der Frontend-Entwicklung, Backend-Entwicklung, Integration von KI-Fähigkeiten und Produktdesign vereint. +| Phase | Kernkompetenzen | Ergebnis | +| ------------ | -------------------------------- | ----------------------------------------- | +| **Phase 1** | KI-Programmierung, Produktdenken, Prototyping | Interaktive Minispiele, Web-Prototypen (Anfänger & PM) | +| **Phase 2** | Full-Stack-Entwicklung, KI-Integration, Datenbanken | Vollständige Full-Stack-KI-Anwendung | +| **Phase 3** | Fortgeschrittener Claude Code, Mobile & Mini-Programme | Multi-Plattform-Anwendungen auf Produktionsniveau | +| **Anhang** | Verständnis grundlegender Konzepte von Computer & KI | 9 Wissensbereiche, 80+ interaktive Themen | -> **Dieses Projekt richtet sich hauptsächlich an drei Arten von Lernenden:** -> -> - **Anfänger (normale Menschen / Produkt und Betrieb)**: Nicht-technische Lernende helfen, Schlüsselkonzepte zu verstehen und ihren ersten Produktprototyp zu completed -> - **Entwickler auf Anfänger-Fortgeschrittenen-Niveau (Studenten und Entwickler mit gewisser Grundlage)**: Beherrschung von Vibe Coding Frontend/Backend und KI-Fähigkeitswissen -> - **Fortgeschrittene Entwickler (Unternehmen und Startups, Open Source und unabhängige Entwickler)**: Fortgeschrittene Entwicklungstechniken, plattformübergreifende Entwicklung - -### 📖 Inhaltsnavigation - -
- Learning Map -
- -### Gesamtanhang - -[KI-Fähigkeitslexikon: gängige KI-Kernkonzepte und Begriffe, Szenario-Erklärungen](docs/zh-cn/appendix/ai-capability-dictionary.md) - -### 1. Anfängereinstieg und Produktprototyp - -| Kapitel | Schlüsselinhalt | Status | -| :------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- | :----- | -| [Vorwort: Lernkarte](docs/zh-cn/stage-0/0.1-learning-map/index.md) | Gesamtführung durch den Lernpfad | ✅ | -| [Anfänger 1: KI-Zeitalter, wenn du sprechen kannst, kannst du programmieren](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Erste Erfahrung mit KI-Programmierfähigkeiten durch Fälle wie Snake | ✅ | -| [Anfänger 2: KI-IDE-Tools kennenlernen](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | IDE-Nutzung lernen, lokal Mini-Spiele erstellen | ✅ | -| [Anfänger 3: Einen Prototyp selbst bauen](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | Anforderungsanalyse, KI-generierte Einzelseite, bis zu Generierung von Mehrseiten-Produktprototypen | ✅ | -| [Anfänger 4: KI-Fähigkeiten zum Prototyp hinzufügen](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Verbindung gängiger KI-Fähigkeiten (Text, Bild, Video) lernen | ✅ | -| [Anfänger 5: Komplettes Projektpraxis](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Reale Szenarien simulieren, Benutzerfeedback zur Iteration akzeptieren, Projekt completed | ✅ | -| [Großes Projekt: Einen kompletten Web-App-Prototyp erstellen und präsentieren](docs/zh-cn/stage-1/1.5-final-project/index.md) | Anwendung vollständig implementieren, Anwendungseffekte präsentieren | ✅ | - -#### Anhänge: Geschäftsdenken - -| Kapitel | Schlüsselinhalt | Status | -| :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | :----- | -| [Anhang A: Produktdenken und Lösungsdesign](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Denkrahmen, die für die Erstellung eines Produkts von Null auf Eins erforderlich sind | ✅ | -| [Anhang B: Referenz für KI-Branchenanwendungsszenarien (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | Verstehen der KI-Anwendungen in verschiedenen Branchen | ✅ | -| [Anhang C: Referenz für KI-Verbrauchsszenarien-Inspiration (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | Erkunden der KI-Anwendungen in Verbraucherprodukten | ✅ | - -#### Anhänge: Technische Lösungen - -| Kapitel | Schlüsselinhalt | Status | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :----- | -| [Anhang D: Was Tun bei Fehlern beim Schreiben von Code](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Häufige Fehler in Vibe Coding und Methoden zur Fehlerbehebung | ✅ | -| [Anhang E: Vergleich von 7 KI-Programmierungstools](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Vergleich und Testen der wichtigsten KI-Programmierplattformen | ✅ | -| [Anhang F: Websites mit Design- und Programmieragenten Entwerfen](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Lernen der kollaborativen Nutzung von KI-Agenten | ✅ | - -### 2. Entwicklungsingenieur auf Anfänger-Fortgeschrittenen-Niveau - -#### Frontend-Teil - -| Kapitel | Schlüsselinhalt | Status | -| :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- | -| [Frontend 0: lovart für Asset-Generierung verwenden](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | lovart für Batch-Generierung von visuellen Assets wie Charakteren und Szenen verwenden, Bereitstellung von Asset-Basis für UI-Design und Frontend-Entwicklung | 🚧 | -| [Frontend 1: Einführung in Figma und MasterGo](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Design-Tools zur Organisation der Informationsarchitektur und Seitenstruktur verwenden, Basis für Frontend-Implementierung schaffen | 🚧 | -| [Frontend 2: Erste moderne Anwendung erstellen - UI-Design](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Komponentenbasierte Schnittstelle basierend auf Entwürfen completed, erste Route von Design zu Code realisieren | 🚧 | -| [Frontend 3: UI-Design-Spezifikationen und Multi-Produkt-UI-Design referenzieren](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Multi-Produkt-Schnittstellen um ein einheitliches Hauptvisuelles erweitern, systematische Designfähigkeiten üben | 🚧 | -| [Frontend 4: Gemeinsam Hogwarts-Porträts erstellen](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | Frontend-Anwendung mit integrierten KI-Fähigkeiten von 0 auf 1 erstellen, Design und Entwicklung verbinden | ✅ | - -#### Backend- und Full-Stack-Teil - -| Kapitel | Schlüsselinhalt | Status | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :----- | -| [Backend 1: Was ist eine API](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTP-Schnittstellen und Request-Response-Modelle verstehen, Vorbereitung auf Backend-Integration und Abstimmung | ✅ | -| [Backend 2: Von Datenbanken zu Supabase](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) : Datenbanken und APIs auf Supabase implementieren, Datenmodelle mit Frontend-Seiten verbinden | ✅ | -| [Backend 3: LLM-unterstützte Schnittstellen- und Dokumentationscodierung](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) : LLM zur Unterstützung bei der Generierung von Dokumentation und Code für Schnittstellen und Datenbanken verwenden, lesbaren und testbaren Backend realisieren | 🚧 | -| [Backend 4: Git-Workflow](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) : Code in Git-Workflow verwalten, Versionskontrolle und Zusammenarbeit durchführen | ✅ | -| [Backend 5: Zeabur-Bereitstellung](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) : Anwendung auf Zeabur bereitstellen, um online zu gehen | ✅ | -| [Backend 6: Moderne CLI-Entwicklungstools](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) : KI-Programmierertools vom Typ CLI verwenden, um Entwicklung und Debugging zu beschleunigen, persönlichen Engineering-Workflow bilden | ✅ | -| [Backend 7: Zahlungssysteme wie Stripe integrieren](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) : Zahlungssysteme anschließen, Zahlungsablauf und grundlegenden Abrechnungsprozess completed | 🚧 | -| [Großes Projekt 1: Erste moderne Anwendung erstellen - Full-Stack-App](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) : Frontend, Backend und Zahlungsmodule integrieren, produktionsreife Full-Stack-Web-Anwendung completed | 🚧 | -| [Großes Projekt 2: Moderne Frontend-Komponentenbibliothek + Trae-Praxis](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) : Moderne Frontend-Komponentenbibliothek und Trae verwenden, unabhängig ein Produkt mit Anmeldung/Registrierung und Zahlungsunterstützung completed | 🚧 | - -#### KI-Fähigkeiten-Anhang - -| Kapitel | Schlüsselinhalt | Status | -| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :----- | -| [KI 1: Einführung in Dify und Wissensbasis-Integration](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) : Dify Workflow und grundlegendes RAG verwenden, um werkzeugartige Produkte zu erstellen, Beispiel für zukünftige Anwendungs-Upgrades erstellen | ✅ | -| [KI 2: KI-Lexikon abfragen und multimodale APIs integrieren lernen](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) : Lernen, geeignete Modelle und APIs zu finden, multimodale Fähigkeiten wie Text und Bild in Produkte integrieren | 🚧 | - -### 3. Fortgeschrittener Entwicklungsingenieur - -| Kapitel | Schlüsselinhalt | Status | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :----- | -| [Fortgeschritten 1: MCP und Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) : IDE-Fähigkeiten durch MCP und Skills erweitern, externe Dienste als Tools anschließen | 🚧 | -| [Fortgeschritten 2: Coding Tools lange laufen lassen](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) : Lang laufende Aufgaben entwerfen und konfigurieren, Coding Tools stabiler und zuverlässiger machen | 🚧 | -| [Fortgeschritten 3: Plattformübergreifende Entwicklung: WeChat-Miniprogramme erstellen](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) : WeChat-Miniprogramm-Ökosystem verstehen, Frontend-Miniprogramm von offizieller Vorlage bis zum Start completed | ✅ | -| [Fortgeschritten 4: Plattformübergreifende Entwicklung: WeChat-Miniprogramme erstellen - Mit Backend](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) : Datenbank und Backend-Logik in Miniprogramme integrieren, vollständigen Geschäftskreislauf realisieren | 🚧 | -| [Fortgeschritten 5: Plattformübergreifende Entwicklung: Android-Anwendungen erstellen](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) : Tools wie Expo verwenden, Web/native-integrierte Android-Anwendungsentwicklung completed | 🚧 | -| [Fortgeschritten 6: Plattformübergreifende Entwicklung: iOS-Anwendungen erstellen](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) : Tools wie Expo verwenden, Web/native-integrierte iOS-Anwendungsentwicklung completed | 🚧 | -| [Fortgeschritten 7: Eigene persönliche Website und akademischen Blog erstellen](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) : Von Auswahl, Erstellung bis Bereitstellung, langfristige Online-Homepage erstellen, die persönliche Projekte und akademische Ergebnisse präsentiert | 🚧 | - -#### KI-Fähigkeiten-Anhang - -| Kapitel | Schlüsselinhalt | Status | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :----- | -| [Fortgeschrittene KI 1: Was ist RAG und wie funktioniert es](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) : Systematisches Verständnis von RAG-Prinzipien und gängigen Architekturen, Wissensretrieval-Basis für komplexe Anwendungen bereitstellen | ✅ | -| [Fortgeschrittene KI 2: Mittel-fortgeschrittenes RAG und Workflow-Orchestrierung: LangGraph-Beispiel](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) : Tools wie LangGraph verwenden, um mehrstufige Workflows und mittel-fortgeschrittene RAG-Systeme zu entwerfen | 🚧 | - -## 🛠️ Lernmethode - -- Entsprechend deiner persönlichen Fähigkeiten selektiv relevante Kapitel lesen und üben, bei Fragen in Issues stellen. - -## 💻 Dieses Kurs lokal starten - -### Moderne Methode - -Gib im KI-IDE-Dialogfeld (vscode, cursor, trae etc.) den folgenden Prompt ein, um diesen Kurs zu starten: - -``` -Bitte hilf mir, den lokalen Service dieses Projekts auszuführen -``` - -### Alte Methode - -1. npm install -2. npm run dev -3. Browser öffnen und `http://localhost:3000` besuchen. - -## 🤝 Mitwirken - -- Wenn du Probleme entdeckst oder denkst, dass es Möglichkeiten zur Verbesserung dieses Projekts gibt, kannst du eine Issue einreichen, um Feedback zu geben. Wenn nach Einreichung niemand antwortet, kannst du das [Betreuer-Team](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) für Feedback und Nachverfolgung kontaktieren~ -- Wenn du zu diesem Projekt beitragen möchtest, kannst du einen Pull Request einreichen, wenn nach Einreichung niemand antwortet, kannst du das [Betreuer-Team](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) für Feedback und Nachverfolgung kontaktieren~ -- Wenn du sehr an Datawhale interessiert bist und ein neues Projekt starten möchtest, folge bitte dem [Datawhale-Open-Source-Projekt-Leitfaden](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)~ - -## 🙏 Dank an jeden Beitragenden - -- [散步-Projektleiter](https://github.com/sanbuphy) (Datawhale-Mitglied) -- Fang Ke-Betreuer (Datawhale-Mitglied, Tsinghua-Universität) -- [Yerim Kang](https://github.com/yerim25)（Praxisprojektteil-Tsinghua-Universität） -- Zhao Zhilin（Praxisprojektteil-Tsinghua-Universität） -- [Li Yixuan](https://yixuan20.github.io/)（Seiten-Kunst-Design-Tsinghua-Universität） -- Alle Kameraden der AI Vibe Coding 101-Beta-Testgruppe, die Vorschläge und Erfahrungen eingebracht haben - -### Besonderer Dank - -- Danke an [@Sm1les](https://github.com/Sm1les) für die Hilfe und Unterstützung bei diesem Projekt -- Danke an alle Entwickler, die zu diesem Projekt beigetragen haben ❤️ - -
- - - -
- -## 📧 Kontaktiere uns - -
-

Bei Fragen, Vorschlägen, Beschwerden oder zum Austausch scanne bitte den untenstehenden QR-Code

- - -

Scan den untenstehenden QR-Code, um dem offiziellen Konto zu folgen: Datawhale

- -
- -## 📄 LIZENZ - -
- - Creative Commons Lizenz - -
-Dieses Werk ist lizenziert unter einer - - Creative Commons Namensnennung - Nicht-kommerziell - Weitergabe unter gleichen Bedingungen 4.0 International Lizenz - -
- -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=datawhalechina/easy-vibe&type=date&legend=top-left)](https://www.star-history.com/#datawhalechina/easy-vibe&type=date&legend=top-left) +*(Details siehe Online-Dokumentation oder Haupt-Repository)* diff --git a/docs-readme/en-US/README.md b/docs-readme/en-US/README.md index 4a56c55..c3c4bad 100644 --- a/docs-readme/en-US/README.md +++ b/docs-readme/en-US/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _Zero Foundation, Project-Based Learning, Build Your First AI Product_ +# Easy-Vibe : Learn vibe coding from 0 to 1

- 📌 Start Reading Online + 📌 Read Online · ✨ Interactive Tutorial

- Online Reading · - Learning Map · + Read Online · + Learning Map · Community

@@ -33,170 +31,351 @@

- 简体中文 - 繁體中文 - English - 日本語 - Español - Français - Klingon - 한국어 - العربية - Türkçe - Tiếng_Việt - Deutsch - বাংলা + 简体中文 + 繁體中文 + English + 日本語 + Español + Français + Klingon + 한국어 + العربية + Türkçe + Tiếng_Việt + Deutsch + বাংলা

- -## 🚀 Project Introduction - -When you try to write code with AI, encounter constant errors, often want to give up, and are unclear about how to actually deploy your programs online 😢. - -This tutorial is specifically designed to take you from 0 to 1, progressively mastering Vibe Coding techniques: - -- **Stage 1**: From **Games to Web Prototypes**, mastering AI programming basics and product thinking (Novice & PM) -- **Stage 2**: Learn **frontend/backend development and AI capabilities** related vibe coding techniques, complete full applications -- **Stage 3**: Master **multi-platform complex application** construction solutions, moving towards production-grade applications - -We believe that by mastering Vibe Coding combined with systematic training, one person can become a developer combining frontend, backend, AI capability integration, and product design. - -> **This project is primarily designed for three types of learners:** -> -> - **Beginners (ordinary people / product and operations)**: Help non-technical beginners understand key concepts and complete their first product prototype. -> - **Intermediate Developers (students and developers with some foundation)**: Master frontend/backend vibe coding and AI capability knowledge. -> - **Advanced Developers (companies and startups, open source and independent developers)**: Advanced development techniques, multi-platform development. - -### 📖 Content Navigation - + + + + + + + + + + + + + +
+ +
+ Exclusive Learning Map for Beginners +
+ Zero-foundation guidance, clear path planning, say goodbye to "learn and forget" + 		+ +
+ Step-by-Step Graphical Tutorial +
+ Nanny-level detailed explanations, like having a private tutor nearby, just follow along +
+ +
+ Immersive Simulated Programming +
+ Virtual mouse auto-navigation, guiding you through core IDE usage quickly + 		+ +
+ Visible AI Principles +
+ Algorithm principles animated, see at a glance how AI "draws" images +
+ +
+ Learn RAG Like Playing a Game +
+ Exclusive interactive components, click to see the RAG data flow clearly + 		+ +
+ Visualized Terminal Principles +
+ Command-line operations visualized, intuitively showcasing background logic and principles +
- Learning Map +

⭐ Welcome to Star here to accelerate updates ❤️

-### Appendix +In the AI era, those who turn ideas into products are often not the ones with the strongest technical skills, but the ones who take the first step. -[AI Capability Dictionary: Common AI Core Concepts, Terminology, and Scenario Explanations](docs/zh-cn/appendix/ai-capability-dictionary.md) +Many people, even with AI assistants, are still discouraged by "not understanding the code" or "not knowing how to configure the environment." **Easy-Vibe was born for this.** Assuming everyone starts from zero foundation, we take you by the hand from writing your first line of code to understanding front-end and back-end logic, and finally launching your product. -### Stage 1: Novice & PM - From Games to Web Prototypes +- **Target Audience**: Beginners, Product Managers, Front-end / Back-end / Full-stack Developers +- **Themes**: AI Programming, Full-stack Web Application Development, AI Agent, Workflow, and RAG Systems -| Chapter | Key Content | Status | -| :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :----- | -| [Preface: Learning Map](docs/en-us/stage-0/) | Overall learning path overview | 🚧 | -| [Primary 1: Programming by Speaking in the AI Era](docs/en-us/stage-0/) | Experience AI programming capabilities through Snake and other cases | 🚧 | -| [Primary 2: Understanding AI IDE Tools](docs/en-us/stage-0/) | Learn to use IDE, create small games locally | 🚧 | -| [Primary 3: Building Prototypes Hands-On](docs/en-us/stage-0/) | From requirement analysis, AI-generated single page to multi-page product prototype | 🚧 | -| [Primary 4: Adding AI Capabilities to Prototypes](docs/en-us/stage-0/) | Learn to integrate common AI capabilities (text, image, video) | 🚧 | -| [Primary 5: Complete Project Practice](docs/en-us/stage-0/) | Simulate real scenarios, accept user feedback iterations, complete projects | 🚧 | -| [Final Assignment: Build a Complete Web Application Prototype and Present](docs/en-us/stage-0/) | Fully implement application, showcase application effects | 🚧 | +--- + +Easy-Vibe takes you from 0 to 1 through the following stages: + +| Stage | Core Skills | Output | +| ------------ | -------------------------------- | ----------------------------------------- | +| **Stage 1** | Intro to AI Programming, Product Thinking, Prototyping | Interactive Mini-games, Web App Prototypes (Beginner & PM) | +| **Stage 2** | Full-stack Development, AI Integration, Databases | Complete Full-stack AI Application | +| **Stage 3** | Advanced Claude Code, Mini-programs & Android Development | Production-grade Multi-platform Applications | +| **Appendix** | Helping you understand Computer & AI basic concepts | 9 Knowledge Domains, 80+ Interactive Topics | + +## 🔥 News + +- **[2026-02-25]** Updated [Appendix Knowledge Base](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/), covering 9 knowledge domains and 80+ interactive topics. +- **[2026-01-27]** Added Android and iOS platform application development tutorials. +- **[2026-01-19]** Released interactive demonstration components for Prompt Engineering, AI Evolution, Authentication Design, Git Principles, etc., significantly enhancing the visual learning experience. + +
+Past News + +- **[2026-01-16]** Restructured project, formally established the "Beginner Entry" chapter to lower the entry barrier. +- **[2026-01-14]** Completed a major update of the Stage 1 "Product Prototype Construction" documentation. +- **[2026-01-13]** Completed document architecture refactoring, fully supporting multi-language (i18n). +- **[2026-01-01]** Released the project's core Learning Map, clarifying the learning path. +
+ +### 📖 Navigation + +
+ Learning Map +
+ +### 📚 Appendix Knowledge Base + +> Covering **9 knowledge domains** and **80+ interactive topics**, using animations and visual components to help you intuitively understand core concepts from computer fundamentals to the AI frontier. +> +> 👉 [View Full Appendix](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) · [AI Capability Dictionary](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary) + + + + + + + + + + + + + + + + + +
+ 💻 Computer Fundamentals

+ • From Transistor to CPU
+ • Operating Systems
+ • Data Encoding, Storage & Transmission
+ • Networks: How Two Computers Talk
+ • Data Structures
+ • Intro to Algorithmic Thinking + 		+ 🔧 Development Tools

+ • Git: The Time Machine of Code
+ • Command Line & Shell Scripting
+ • Package Managers
+ • The Art of Debugging
+ • Regular Expressions
+ • Environment Variables & PATH + 		+ 🌐 Browser & Front-end

+ • Deep Dive into JavaScript
+ • Browser Rendering Pipeline
+ • Front-end Framework Comparison
+ • Graphics & Animation
+ • Web Performance Measurement & Optimization
+ • The Big Picture of Front-end Engineering +
+ 🖥️ Server & Back-end

+ • HTTP Protocol
+ • API Design Philosophy
+ • Authentication & Authorization
+ • Concurrency, Async & Multithreading
+ • Message Queues & Event-Driven
+ • Back-end Layered Architecture + 		+ 📊 Data

+ • SQL
+ • Database Fundamentals
+ • Tracking & User Behavior Collection
+ • Data Analysis Basics
+ • A/B Testing & Experiment Driven
+ • Data Visualization & Dashboards + 		+ 🏗️ Architecture & System Design

+ • Evolution from Monolith to Microservices
+ • Challenges of Distributed Systems
+ • High Availability & Disaster Recovery
+ • System Design Methodology +
+ ☁️ Infrastructure & DevOps

+ • Docker Containerization
+ • Kubernetes Orchestration
+ • CI / CD Automation
+ • Domains, DNS & HTTPS
+ • Monitoring, Logging & Alerting
+ • Infrastructure as Code + 		+ 🤖 Artificial Intelligence

+ • How LLMs Work
+ • Transformer & Attention Mechanism
+ • RAG Architecture
+ • AI Agents & Tool Calling
+ • Prompt Engineering
+ • Image Generation Principles + 		+ 🎯 Engineering Excellence

+ • Code Quality & Refactoring
+ • Testing Strategies
+ • Design Patterns
+ • Security Thinking & Defense Basics
+ • Technical Writing
+ • Open Source Collaboration +
+ +### I. Zero Foundation Entry + +| Chapter | Key Content | Status | +| :----------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | +| [Preface: Learning Map](../../docs/zh-cn/stage-0/0.1-learning-map/index.md) | Overall learning path navigation | ✅ | +| [Level 1: AI Era, Speaking is Programming](../../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Experience AI programming through cases like Snake | ✅ | +| [Level 2: Finding Great Ideas](../../docs/zh-cn/stage-1/1.0-finding-great-idea/index.md) | Learn to find and validate product ideas | ✅ | +| [Level 3: Intro to AI IDE Tools](../../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | Learn to use IDE, make games locally | ✅ | +| [Level 4: Building Prototypes Hands-on](../../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | From requirements to single and multi-page prototypes | ✅ | +| [Level 5: Adding AI Power to Prototypes](../../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Learn to integrate AI (text, image, video) | ✅ | +| [Level 6: Full Project Practice](../../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Simulate real scenarios, iterate with feedback | ✅ | #### Appendix: Business Thinking -| Chapter | Key Content | Status | -| :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------- | :----- | -| [Appendix A: Product Thinking and Solution Design](docs/en-us/stage-1/appendix-a-product-thinking/) | Thinking framework needed to build products from scratch | 🚧 | -| [Appendix B: AI Industry Application Scenarios (B2B)](docs/en-us/stage-1/appendix-industry-scenarios/) | Understand AI applications in different industries | 🚧 | -| [Appendix C: AI Consumer Scenario Inspiration (B2C)](docs/en-us/stage-1/appendix-c-consumer-scenarios/) | Explore AI applications in consumer products | 🚧 | +| Chapter | Key Content | Status | +| :----------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [Appendix A: Product Thinking & Solution Design](../../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Thinking frameworks for building products | ✅ | +| [Appendix B: AI Industry Scenarios (B2B)](../../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | AI applications in different industries | ✅ | +| [Appendix C: AI Consumer Scenarios (B2C)](../../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | AI application scenarios in consumer products | ✅ | #### Appendix: Technical Solutions -| Chapter | Key Content | Status | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- | :----- | -| [Appendix D: What to Do When Encountering Errors](docs/en-us/stage-1/appendix-b-common-errors/) | Common errors in vibe coding and troubleshooting methods | 🚧 | -| [Appendix E: Comparison of Seven AI Programming Tools](docs/en-us/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Compare and test mainstream AI programming platforms | 🚧 | -| [Appendix F: Designing Websites with Design and Programming Agents](docs/en-us/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Learn how to use AI agents collaboratively | 🚧 | +| Chapter | Key Content | Status | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [Appendix D: Handling Errors](../../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Common errors and troubleshooting in vibe coding | ✅ | +| [Appendix E: Comparison of 7 AI Programming Tools](../../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Direct comparison of mainstream platforms | ✅ | +| [Appendix F: Designing Websites with Design & Programming Agents](../../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Multi-agent collaboration for web design | ✅ | -### Stage 2: Intermediate Developer +
+II. Intermediate Developer -#### Frontend Part +#### Front-end -| Chapter | Key Content | Status | -| :----------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----- | -| [Frontend 0: Using Lovart to Generate Assets](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Learn to use Lovart to batch generate characters, scenes and other visual assets | 🚧 | -| [Frontend 1: Figma & MasterGo Introduction](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Use design tools to organize information architecture and page structure | 🚧 | -| [Frontend 2: Building Your First Modern Application - UI Design](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Complete componentized interface based on design specs, implement the first link from design to code | 🚧 | -| [Frontend 3: Reference UI Design Specs and Multi-Product UI Design](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Expand multi-product interfaces around unified visual design, practice systematic design capabilities | 🚧 | -| [Frontend 4: Building Hogwarts Portraits Together](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | Build AI-capable frontend applications from scratch, connecting design and development | ✅ | +| Chapter | Key Content | Status | +| :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | +| [Front-end 0: Assets with Lovart](../../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Batch generate visual assets like characters/scenes | 🚧 | +| [Front-end 1: Figma & MasterGo Intro](../../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Organize info architecture and page structure | 🚧 | +| [Front-end 2: Building First Modern App - UI Design](../../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Design-to-code workflow with components | 🚧 | +| [Front-end 3: UI Design Specs & Multi-product UI](../../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Systematic design across multiple products | 🚧 | +| [Front-end 4: Hogwarts Portraits Together](../../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | Build an AI-powered front-end app from 0 to 1 | ✅ | -#### Backend and Full Stack Part +#### Back-end & Full-stack -| Chapter | Key Content | Status | -| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :----- | -| [Backend 1: What is API](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | Understand HTTP interfaces and request-response models | ✅ | -| [Backend 2: From Database to Supabase](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Implement databases and APIs on Supabase, connect data models with frontend pages | ✅ | -| [Backend 3: AI-Assisted Interface Code and Documentation](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | Use LLM to help generate interface and database documentation and code | 🚧 | -| [Backend 4: Git Workflow](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Manage code in Git workflow, version control and collaboration | ✅ | -| [Backend 5: Zeabur Deployment](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Deploy applications to Zeabur for production | ✅ | -| [Backend 6: Modern CLI Development Tools](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | Use CLI-based AI programming tools to accelerate development and debugging | ✅ | -| [Backend 7: Integrating Payment Systems like Stripe](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | Integrate payment systems, complete payment links and basic settlement processes | 🚧 | -| [Assignment 1: Build Your First Modern Application - Full Stack](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | Integrate frontend, backend and payment modules, complete production-ready full stack web application | 🚧 | -| [Assignment 2: Modern Frontend Component Library + Trae Practice](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | Use modern frontend component libraries with Trae, independently complete login/registration and payment-capable products | 🚧 | +| Chapter | Key Content | Status | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | +| [Back-end 1: What is an API](../../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTP interfaces and request-response models | ✅ | +| [Back-end 2: DB to Supabase](../../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Implement DB and API on Supabase | ✅ | +| [Back-end 3: AI-Assisted API Code & Docs](../../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | Generate API/DB docs and code with LLM | 🚧 | +| [Back-end 4: Git Workflow](../../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Version control and collaboration in Git | ✅ | +| [Back-end 5: Zeabur Deployment](../../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Deploy applications to Zeabur | ✅ | +| [Back-end 6: Modern CLI Dev Tools](../../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | Accelerate dev with CLI-based AI tools | ✅ | +| [Back-end 7: Integrating Payment Systems like Stripe](../../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | Integrate payment and basic settlement flow | 🚧 | +| [Project 1: First Modern Application - Full-stack App](../../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | Complete localized, production-ready Full-stack Web App | 🚧 | +| [Project 2: Modern UI Library + Trae Practice](../../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | Independent product with auth and payment | 🚧 | -#### AI Capabilities Appendix +#### AI Capability Appendix -| Chapter | Key Content | Status | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :----- | -| [AI 1: Dify Introduction and Knowledge Base Integration](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Use Dify Workflow and basic RAG to build utility products | ✅ | -| [AI 2: Learn to Query AI Dictionary and Integrate Multimodal APIs](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | Learn to find suitable models and APIs, integrate text, image and other multimodal capabilities | 🚧 | +| Chapter | Key Content | Status | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- | +| [AI 1: Dify Intro & Knowledge Base](../../docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Build utility products with Dify Workflow & RAG | ✅ | +| [AI 2: AI Dictionary & Multimodal APIs](../../docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | Research models/APIs and integrate multimodal power | 🚧 | -### Stage 3: Advanced Developer +
-| Chapter | Key Content | Status | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :----- | -| [Advanced 1: MCP and Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | Extend IDE capabilities through MCP and Skills, integrate external services as tools | 🚧 | -| [Advanced 2: Making Coding Tools Work for Long Periods](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | Design and configure long-running tasks, make Coding Tools more stable and reliable | 🚧 | -| [Advanced 3: Multi-Platform Development: Building WeChat Mini Programs](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | Understand WeChat mini program ecosystem, complete a frontend mini program from official template to launch | ✅ | -| [Advanced 4: Multi-Platform Development: Building WeChat Mini Programs - With Backend](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | Integrate databases and backend logic in mini programs, complete business loops | 🚧 | -| [Advanced 5: Multi-Platform Development: Building Android Apps](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Use Expo and other tools to complete Web/native integrated Android application development | 🚧 | -| [Advanced 6: Multi-Platform Development: Building iOS Apps](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Use Expo and other tools to complete Web/native integrated iOS application development | 🚧 | -| [Advanced 7: Building Your Personal Website and Academic Blog](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | From selection, building to deployment, create a permanent online homepage showcasing projects and academic achievements | 🚧 | +
+III. Advanced Developer -#### AI Capabilities Appendix +| Chapter | Key Content | Status | +| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | +| [Advanced 1: MCP & Claude Code Skills](../../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | Extend IDE power with external services as tools | 🚧 | +| [Advanced 2: Long-running Coding Tasks](../../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | Design and configure stable, long-running tasks | 🚧 | +| [Advanced 3: WeChat Mini Program Dev](../../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | Build and launch a front-end mini program | ✅ | +| [Advanced 4: WeChat Mini Program with Back-end](../../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | Integrate DB and back-end logic in mini programs | 🚧 | +| [Advanced 5: Android App Development](../../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Web/Native unified Android dev with Expo | ✅ | +| [Advanced 6: iOS App Development](../../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Web/Native unified iOS dev with Expo | ✅ | +| [Advanced 7: Personal Website & Academic Blog](../../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | Build and deploy a permanent online homepage | 🚧 | -| Chapter | Key Content | Status | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :----- | -| [Advanced AI 1: What is RAG and How It Works](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | Systematically understand RAG principles and common architectures | ✅ | -| [Advanced AI 2: Intermediate/Advanced RAG and Workflow Orchestration with LangGraph](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | Use LangGraph and other tools to design multi-step workflows and intermediate/advanced RAG systems | 🚧 | +#### AI Capability Appendix + +| Chapter | Key Content | Status | +| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :--- | +| [Advanced AI 1: What is RAG & How It Works](../../docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | Systematic understanding of RAG architectures | ✅ | +| [Advanced AI 2: Advanced RAG with LangGraph](../../docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | Multi-step workflows and advanced RAG systems | 🚧 | + +
## 🛠️ How to Learn -- Choose relevant chapters to read and practice based on your personal ability. If you have questions, feel free to ask via issues. +- Choose chapters to read and practice based on your skill level. Feel free to open an issue for questions. -## 💻 Running This Course Locally +## 💻 Local Setup ### Modern Approach -In the AI IDE dialog box (vscode, cursor, trae, etc.), enter the following prompt to start this course: +In an AI IDE (VS Code, Cursor, Trae, etc.), use the following prompt: ``` -Please help me run this project's local service +Please help me run the local service for this project. ``` ### Traditional Approach 1. npm install 2. npm run dev -3. Open your browser and visit `http://localhost:3000` to view. +3. Open `http://localhost:3000` in your browser. ## 🤝 Contributing -- If you discover any problems or see areas for improvement, please submit an Issue for feedback. If there's no response after submitting, you can contact the [Nanny Team](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) for follow-up. -- If you want to contribute to this project, please submit a Pull Request. If there's no response after submitting, you can contact the [Nanny Team](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) for follow-up. -- If you're very interested in Datawhale and want to start a new project, please follow the [Datawhale Open Source Project Guide](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md). +- If you find issues or have suggestions, please open an Issue. If you don't get a response, contact the [Nanny Team](https://github.com/datawhalechina/DOPMC/blob/main/OP.md). +- To contribute, please submit a Pull Request. +- If you want to start a new project with Datawhale, follow the [Datawhale Open Source Project Guide](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md). -## 🙏 Thanks to Every Contributor +## 🙏 Acknowledgements - [Sanbu - Project Lead](https://github.com/sanbuphy) (Datawhale Member) - Fang Ke - Advisor (Datawhale Member, Tsinghua University) -- [Yerim Kang](https://github.com/yerim25) (Practice Project Section - Tsinghua University) -- Zhao Zhilin (Practice Project Section - Tsinghua University) -- [Li Yixuan](https://yixuan20.github.io/) (Page Art Design - Tsinghua University) -- All friends from the AI Vibe Coding 101 Beta Group who provided suggestions and experience +- [Yerim Kang](https://github.com/yerim25) (Practice Projects - Tsinghua University) +- Zhao Zhilin (Practice Projects - Tsinghua University) +- [Li Yixuan](https://yixuan20.github.io/) (Visual Design - Tsinghua University) +- Liu Siyi (Practice Projects - Tsinghua University) +- All Beta testers from the AI Vibe Coding 101 group for their feedback. ### Special Thanks -- Thanks to [@Sm1les](https://github.com/Sm1les) for their help and support with this project -- Thanks to all developers who contributed to this project ❤️ +- Thanks to [@Sm1les](https://github.com/Sm1les) for support and help. +- Thanks to all contributors and everyone who starred this project ❤️ + +
+ +

+ Stargazers +    + Forkers +

+ + + + + + + +
@@ -207,10 +386,10 @@ Please help me run this project's local service ## 📧 Contact Us
-

If you have questions, suggestions, or want to communicate together, please scan the QR code below

- +

For questions, suggestions, or collaboration, please scan the QR code below:

+ -

Scan the QR code below to follow the official account: Datawhale

+

Follow Datawhale on WeChat:

@@ -219,7 +398,7 @@ Please help me run this project's local service
Creative Commons License diff --git a/docs-readme/es-ES/README.md b/docs-readme/es-ES/README.md index 2dc404c..281d65a 100644 --- a/docs-readme/es-ES/README.md +++ b/docs-readme/es-ES/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _Desde cero, aprendizaje basado en proyectos, construyendo tu primer producto de IA_ +# Easy-Vibe : Aprende Vibe Coding de 0 a 1

- 📌 Comenzar a leer en línea (Start Reading Online) + 📌 Leer en línea (Read Online) · ✨ Tutorial interactivo

Leer en línea · - Mapa de aprendizaje · + Mapa de aprendizaje · Comunidad

@@ -37,163 +35,323 @@ 繁體中文 English 日本語 - Español + Español Français + Klingon 한국어 العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

- -## 🚀 Introducción al Proyecto - -Cuando intentas escribir código con IA, encuentras errores constantes, a menudo quieres rendirte y no está claro cómo llevar realmente tus programas en línea 😢. - -Este tutorial está específicamente diseñado para llevarte de 0 a 1, dominando progresivamente las técnicas de Vibe Coding: - -- **Etapa 1**: **De mini juegos a prototipos web**, dominar los conceptos básicos de programación de IA y pensamiento de producto -- **Etapa 2**: Aprender **desarrollo frontend/backend y capacidades de IA** relacionadas con técnicas de Vibe Coding, completando una aplicación completa -- **Etapa 3**: Dominar la construcción de **aplicaciones complejas multiplataforma**, avanzando hacia aplicaciones de nivel de producción - -Creemos que al dominar Vibe Coding y combinarlo con entrenamiento sistemático, una sola persona puede convertirse en un desarrollador que combine desarrollo frontend, desarrollo backend, integración de capacidades de IA y diseño de productos. - -> **Este proyecto está dirigido principalmente a tres tipos de estudiantes:** -> -> - **Principiantes (personas comunes / producto y operaciones)**: Ayudar a estudiantes no técnicos a entender conceptos clave y completar su primer prototipo de producto -> - **Desarrollores de nivel principiante-intermedio (estudiantes y desarrolladores con cierta base)**: Dominar el conocimiento de Vibe Coding frontend/backend y capacidades de IA -> - **Desarrollores avanzados (empresas y startups, código abierto e desarrollores independientes)**: Técnicas avanzadas de desarrollo, desarrollo multiplataforma - -### 📖 Navegación de Contenido - + + + + + + + + + + + + + +
+ +
+ Mapa de aprendizaje exclusivo para principiantes +
+ Guía desde cero, planificación de ruta clara, adiós al "aprender y olvidar" + 		+ +
+ Tutorial gráfico paso a paso +
+ Explicaciones detalladas, como tener un tutor privado a tu lado, solo sigue los pasos +
+ +
+ Programación simulada inmersiva +
+ Navegación automática con mouse virtual, aprendiendo rápidamente los usos principales del IDE + 		+ +
+ Principios de IA visibles +
+ Principios de algoritmos animados, entiende de un vistazo cómo la IA "dibuja" imágenes +
+ +
+ Aprende RAG como si fuera un juego +
+ Componentes interactivos exclusivos, haz clic para ver claramente el flujo de datos RAG + 		+ +
+ Principios de terminal visualizados +
+ Operaciones de línea de comandos visualizadas, mostrando intuitivamente la lógica de fondo +
- Learning Map +

⭐ Te invitamos a dar Star aquí para acelerar las actualizaciones ❤️

-### Apéndice General +En la era de la IA, las personas que convierten ideas en productos a menudo no son las que tienen los conocimientos técnicos más sólidos, sino las que dan el primer paso. -[Diccionario de capacidades de IA: conceptos centrales comunes de IA, términos y explicaciones de escenarios](docs/zh-cn/appendix/ai-capability-dictionary.md) +Muchas personas, incluso con asistentes de IA, se desaniman por "no entender el código" o "no saber cómo configurar el entorno". **Easy-Vibe nació para esto.** Asumiendo que todos parten de cero, te llevamos de la mano desde escribir tu primera línea de código hasta entender la lógica del front-end y back-end, y finalmente lanzar tu producto. -### 1. Entrada de Novatos y Prototipo de Producto +- **Público objetivo**: Principiantes, Product Managers, Desarrolladores Front-end / Back-end / Full-stack +- **Temas**: Programación con IA, Desarrollo de aplicaciones Web Full-stack, AI Agent, Workflows y sistemas RAG -| Capítulo | Contenido clave | Estado | -| :---------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :----- | -| [Prólogo: Mapa de aprendizaje](docs/zh-cn/stage-0/0.1-learning-map/index.md) | Guía general de la ruta de aprendizaje | ✅ | -| [Principiante 1: La era de la IA, si puedes hablar puedes programar](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Experimentar por primera vez las capacidades de programación con IA a través de casos como Snake | ✅ | -| [Principiante 2: Conociendo herramientas de IDE de IA](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | Aprender a usar el IDE, crear mini juegos localmente | ✅ | -| [Principiante 3: Haz un prototipo tú mismo](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | Análisis de requisitos, generación de una sola página con IA, hasta generar prototipos de productos de múltiples páginas | ✅ | -| [Principiante 4: Añade capacidades de IA al prototipo](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Aprender a conectar capacidades comunes de IA (texto, imagen, video) | ✅ | -| [Principiante 5: Proyecto completo práctico](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Simular escenarios reales, aceptar feedback de usuarios para iterar, completar el proyecto | ✅ | -| [Proyecto final: Haz un prototipo completo de aplicación web y preséntalo](docs/zh-cn/stage-1/1.5-final-project/index.md) | Implementar completamente la aplicación, mostrar los efectos de la aplicación | ✅ | +--- -#### Apéndices: Pensamiento de Negocio +Easy-Vibe te lleva de 0 a 1 a través de las siguientes etapas: -| Capítulo | Contenido clave | Estado | -| :---------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | :----- | -| [Apéndice A: Pensamiento de Producto y Diseño de Solución](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Marcos de pensamiento necesarios para crear un producto de cero a uno | ✅ | -| [Apéndice B: Referencia de Escenarios de Aplicación de AI en la Industria (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | Comprender las aplicaciones de AI en diferentes industrias | ✅ | -| [Apéndice C: Referencia de Inspiración de Escenarios de Consumo de AI (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | Explorar las aplicaciones de AI en productos de consumo | ✅ | +| Etapa | Habilidades clave | Resultado | +| ------------ | -------------------------------- | ----------------------------------------- | +| **Etapa 1** | Introducción a la programación con IA, Pensamiento de producto, Diseño de prototipos | Minijuegos interactivos, Prototipos de aplicaciones Web (Principiantes & PM) | +| **Etapa 2** | Desarrollo Full-stack, Integración de IA, Bases de datos | Aplicación de IA Full-stack completa | +| **Etapa 3** | Claude Code avanzado, Desarrollo de Miniprogramas y Android | Aplicaciones multiplataforma de nivel de producción | +| **Apéndice** | Ayuda para entender conceptos básicos de Computación e IA | 9 dominios de conocimiento, más de 80 temas interactivos | -#### Apéndices: Soluciones Técnicas +## 🔥 Noticias -| Capítulo | Contenido clave | Estado | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :----- | -| [Apéndice D: Qué Hacer Cuando se Encuentran Errores al Escribir Código](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Errores comunes en Vibe Coding y métodos de solución de problemas | ✅ | -| [Apéndice E: Comparación de 7 Herramientas de Programación AI](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Comparar y probar las principales plataformas de programación AI | ✅ | -| [Apéndice F: Diseñar Sitios Web con Agentes de Diseño y Programación](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Aprender a usar agentes AI de forma colaborativa | ✅ | +- **[2026-02-25]** Actualizada la [Base de conocimientos del apéndice](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/), que cubre 9 dominios de conocimiento y más de 80 temas interactivos. +- **[2026-01-27]** Se agregaron tutoriales de desarrollo de aplicaciones para las plataformas Android e iOS. +- **[2026-01-19]** Lanzamiento de una serie de componentes de demostración interactiva para Prompt Engineering, evolución de la IA, diseño de autenticación, principios de Git, etc. -### 2. Ingeniero de Desarrollo de Nivel Principiante-Intermedio +
+Past News -#### Parte Frontend +- **[2026-01-16]** Reestructuración del proyecto, estableciendo formalmente el capítulo de "Introducción para principiantes". +- **[2026-01-14]** Completada una actualización masiva de la documentación de la Etapa 1 "Construcción de prototipos de productos". +- **[2026-01-13]** Reconstrucción de la arquitectura de documentos, soporte total para multi-idioma (i18n). +- **[2026-01-01]** Lanzamiento del Mapa de Aprendizaje principal del proyecto. +
-| Capítulo | Contenido clave | Estado | -| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | -| [Frontend 0: Usar lovart para generar activos](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Usar lovart para generar por lotes activos visuales como personajes y escenas, proporcionando base de activos para diseño UI y desarrollo frontend | 🚧 | -| [Frontend 1: Introducción a Figma y MasterGo](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Usar herramientas de diseño para organizar arquitectura de información y estructura de páginas, preparando la base para implementación frontend | 🚧 | -| [Frontend 2: Construir la primera aplicación moderna - Diseño UI](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Completar interfaz basada en componentes basada en diseños,实现 la primera ruta de diseño a código | 🚧 | -| [Frontend 3: Referencia de especificaciones de diseño UI y diseño UI de múltiples productos](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Expandir interfaces de múltiples productos en torno a un visual principal unificado, practicar capacidades de diseño sistemático | 🚧 | -| [Frontend 4: Hagamos los retratos de Hogwarts juntos](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | Crear una aplicación frontend con capacidades de IA integradas de 0 a 1, conectando diseño y desarrollo | ✅ | +### 📖 Navegación -#### Parte Backend y Full Stack +
+ Mapa de Aprendizaje +
-| Capítulo | Contenido clave | Estado | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :----- | -| [Backend 1: Qué es una API](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | Entender interfaces HTTP y modelos de solicitud-respuesta, preparándose para integración backend y coordinación | ✅ | -| [Backend 2: De bases de datos a Supabase](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Implementar bases de datos y APIs en Supabase, conectando modelos de datos con páginas frontend | ✅ | -| [Backend 3: LLM asistiendo en la escritura de código de interfaz y documentación](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | Usar LLM para ayudar a generar documentación y código para interfaces y bases de datos,实现 un backend legible y testeable | 🚧 | -| [Backend 4: Flujo de trabajo Git](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Gestionar código en flujo de trabajo Git, realizar control de versiones y colaboración | ✅ | -| [Backend 5: Despliegue Zeabur](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Desplegar la aplicación en Zeabur para ponerla en línea | ✅ | -| [Backend 6: Herramientas de desarrollo CLI modernas](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | Usar herramientas de programación IA tipo CLI para acelerar desarrollo y depuración, formando flujo de ingeniería personal | ✅ | -| [Backend 7: Cómo integrar sistemas de pago como Stripe](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | Conectar sistemas de pago, completar flujo de pago y proceso básico de liquidación | 🚧 | -| [Proyecto final 1: Construir la primera aplicación moderna - Aplicación full stack](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | Integrar frontend, backend y módulos de pago, completar aplicación web full stack lista para producción | 🚧 | -| [Proyecto final 2: Biblioteca de componentes frontend moderna + Trae práctico](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | Usar biblioteca de componentes frontend moderna y Trae, completar independientemente un producto con registro/login y soporte de pago | 🚧 | +### 📚 Base de conocimientos del apéndice -#### Apéndice de Capacidades de IA +> Cubre **9 dominios de conocimiento** y más de **80 temas interactivos**, utilizando animaciones y componentes visuales para ayudarte a comprender intuitivamente los conceptos centrales desde los fundamentos de la computación hasta la frontera de la IA. +> +> 👉 [Ver apéndice completo](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) · [Diccionario de capacidades de IA](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary) -| Capítulo | Contenido clave | Estado | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :----- | -| [IA 1: Introducción a Dify e integración de base de conocimientos](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Usar Dify Workflow y RAG básico para construir productos tipo herramientas, creando ejemplo para actualizaciones futuras de aplicaciones | ✅ | -| [IA 2: Aprender a consultar diccionario de IA e integrar APIs multimodales](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | Aprender a buscar modelos y APIs apropiados, integrar capacidades multimodales como texto e imagen en productos | 🚧 | + + + + + + + + + + + + + + + + +
+ 💻 Fundamentos de Computación

+ • Del transistor a la CPU
+ • Sistemas operativos
+ • Codificación, almacenamiento y transmisión de datos
+ • Redes: Cómo hablan dos ordenadores
+ • Estructuras de datos
+ • Introducción al pensamiento algorítmico + 		+ 🔧 Herramientas de desarrollo

+ • Git: La máquina del tiempo del código
+ • Línea de comandos y scripts de Shell
+ • Gestores de paquetes
+ • El arte de la depuración
+ • Expresiones regulares
+ • Variables de entorno y PATH + 		+ 🌐 Navegador y Front-end

+ • Inmersión profunda en JavaScript
+ • Tubería de renderizado del navegador
+ • Comparación de frameworks front-end
+ • Gráficos y animación
+ • Medición y optimización del rendimiento web
+ • Panorama de la ingeniería front-end +
+ 🖥️ Servidor y Back-end

+ • Protocolo HTTP
+ • Filosofía de diseño de APIs
+ • Autenticación y autorización
+ • Concurrencia, asincronía e hilos
+ • Colas de mensajes y eventos
+ • Arquitectura back-end en capas + 		+ 📊 Datos

+ • SQL
+ • Principios de bases de datos
+ • Recopilación de comportamiento del usuario
+ • Fundamentos de análisis de datos
+ • Pruebas A/B y experimentación
+ • Visualización de datos y dashboards + 		+ 🏗️ Arquitectura y Diseño de Sistemas

+ • Del monolito a los microservicios
+ • Desafíos de sistemas distribuidos
+ • Alta disponibilidad y recuperación
+ • Metodología de diseño de sistemas +
+ ☁️ Infraestructura y Operaciones

+ • Containerización con Docker
+ • Orquestación con Kubernetes
+ • Automatización CI / CD
+ • Dominios, DNS y HTTPS
+ • Monitoreo, registros y alertas
+ • Infraestructura como código + 		+ 🤖 Inteligencia Artificial

+ • Cómo funcionan los LLMs
+ • Transformer y mecanismos de atención
+ • Arquitectura RAG
+ • AI Agents y llamadas a herramientas
+ • Ingeniería de prompts
+ • Principios de generación de imágenes + 		+ 🎯 Excelencia en Ingeniería

+ • Calidad de código y refactorización
+ • Estrategias de prueba
+ • Patrones de diseño
+ • Pensamiento de seguridad y defensa
+ • Redacción técnica
+ • Colaboración de código abierto +
-### 3. Ingeniero de Desarrollo Avanzado +### I. Introducción desde cero -| Capítulo | Contenido clave | Estado | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- | :----- | -| [Avanzado 1: MCP y Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | Extender capacidades del IDE a través de MCP y Skills, conectar servicios externos como herramientas | 🚧 | -| [Avanzado 2: Cómo hacer que Coding Tools funcione durante mucho tiempo](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | Diseñar y configurar tareas de ejecución prolongada, hacer Coding Tools más estable y confiable | 🚧 | -| [Avanzado 3: Desarrollo multiplataforma: Cómo construir mini programas de WeChat](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | Entender el ecosistema de mini programas de WeChat, completar un mini programa frontend desde plantilla oficial hasta lanzamiento | ✅ | -| [Avanzado 4: Desarrollo multiplataforma: Cómo construir mini programas de WeChat - Incluyendo backend](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | Integrar base de datos y lógica backend en mini programas,实现 ciclo completo de negocio | 🚧 | -| [Avanzado 5: Desarrollo multiplataforma: Cómo construir aplicaciones Android](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Usar herramientas como Expo, completar desarrollo de aplicaciones Android integrando Web/nativo | 🚧 | -| [Avanzado 6: Desarrollo multiplataforma: Cómo construir aplicaciones iOS](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Usar herramientas como Expo, completar desarrollo de aplicaciones iOS integrando Web/nativo | 🚧 | -| [Avanzado 7: Cómo construir tu propio sitio web personal y blog académico](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | Desde selección, construcción hasta despliegue, construir homepage en línea a largo plazo mostrando proyectos personales y logros académicos | 🚧 | +| Capítulo | Contenido clave | Estado | +| :----------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | +| [Prólogo: Mapa de aprendizaje](../../docs/zh-cn/stage-0/0.1-learning-map/index.md) | Navegación por la ruta de aprendizaje completa | ✅ | +| [Nivel 1: Era de la IA, hablar es programar](../../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Experimenta la programación con IA mediante casos | ✅ | +| [Nivel 2: Buscando buenas ideas](../../docs/zh-cn/stage-1/1.0-finding-great-idea/index.md) | Aprende a validar ideas de productos | ✅ | +| [Nivel 3: Introducción a las herramientas AI IDE](../../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | Aprende a usar el IDE y crea juegos locales | ✅ | +| [Nivel 4: Construyendo prototipos a mano](../../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | Desde el análisis hasta prototipos de varias páginas | ✅ | +| [Nivel 5: Añadiendo IA a los prototipos](../../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Aprende a integrar IA (texto, imagen, video) | ✅ | +| [Nivel 6: Práctica de proyecto completo](../../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Escenarios reales e iteración con feedback | ✅ | -#### Apéndice de Capacidades de IA +#### Apéndice: Pensamiento de negocio -| Capítulo | Contenido clave | Estado | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | -| [IA Avanzada 1: Qué es RAG y cómo funciona](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | Entender sistemáticamente principios de RAG y arquitecturas comunes, proporcionar base de recuperación de conocimiento para aplicaciones complejas | ✅ | -| [IA Avanzada 2: RAG intermedio-avanzado y orquestación de flujos de trabajo: Ejemplo con LangGraph](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | Usar herramientas como LangGraph para diseñar flujos de trabajo multipaso y sistemas RAG intermedio-avanzados | 🚧 | +| Capítulo | Contenido clave | Estado | +| :----------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [Apéndice A: Pensamiento de producto](../../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Marcos de pensamiento para crear productos | ✅ | +| [Apéndice B: Escenarios industriales de IA (B2B)](../../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | Aplicaciones de IA en diferentes industrias | ✅ | +| [Apéndice C: Inspiración para escenarios B2C](../../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | Exploración de IA en productos de consumo | ✅ | -## 🛠️ Cómo Aprender +#### Apéndice: Soluciones técnicas -- Según tus habilidades personales, lee y practica selectivamente capítulos relevantes, si tienes preguntas hazlas en Issues. +| Capítulo | Contenido clave | Estado | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [Apéndice D: Qué hacer ante errores](../../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Errores comunes en vibe coding y soluciones | ✅ | +| [Apéndice E: Comparación de herramientas AI](../../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Comparativa de plataformas principales | ✅ | +| [Apéndice F: Diseñando sitios con Agentes](../../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Uso de agentes de IA para diseño web | ✅ | -## 💻 Iniciar Este Curso Localmente +
+II. Desarrollador intermedio -### Método Moderno +#### Front-end -En el cuadro de diálogo del IDE de IA (vscode, cursor, trae, etc.), ingresa el siguiente prompt para iniciar este curso: +| Capítulo | Contenido clave | Estado | +| :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | +| [Front-end 0: Activos con Lovart](../../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Generación masiva de activos visuales | 🚧 | +| [Front-end 1: Intro a Figma & MasterGo](../../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Organización de arquitectura de la información | 🚧 | +| [Front-end 2: Construyendo la primera App - UI](../../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Interfaz basada en componentes desde el diseño | 🚧 | +| [Front-end 3: Especificaciones de diseño UI](../../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Diseño sistemático a través de productos | 🚧 | +| [Front-end 4: Retratos de Hogwarts juntos](../../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | App front-end con IA desde cero hasta producción | ✅ | + +#### Back-end y Full-stack + +| Capítulo | Contenido clave | Estado | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | +| [Back-end 1: Qué es una API](../../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | Interfaces HTTP y modelos petición-respuesta | ✅ | +| [Back-end 2: De DB a Supabase](../../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Implementación de bases de datos y APIs | ✅ | +| [Back-end 3: Código de interfaz asistido por IA](../../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | Uso de LLM para generación de código y docs | 🚧 | +| [Back-end 4: Flujo de trabajo Git](../../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Control de versiones y colaboración | ✅ | +| [Back-end 5: Despliegue en Zeabur](../../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Despliegue de aplicaciones para producción | ✅ | +| [Back-end 6: Herramientas CLI modernas](../../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | Aceleración del desarrollo con herramientas AI | ✅ | +| [Back-end 7: Integración de pagos con Stripe](../../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | Procesos de cobro y liquidación básicos | 🚧 | +| [Proyecto 1: Aplicación Full-stack completa](../../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | Web App completa lista para producción | 🚧 | +| [Proyecto 2: UI Library + Trae](../../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | Producto independiente con auth y pagos | 🚧 | + +
+ +
+III. Desarrollador avanzado + +| Capítulo | Contenido clave | Estado | +| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | +| [Avanzado 1: MCP & Claude Code Skills](../../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | Extensión de capacidades del IDE | 🚧 | +| [Avanzado 2: Tareas de larga duración](../../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | Configuración de tareas de codificación estables | 🚧 | +| [Avanzado 3: WeChat Mini Program](../../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | Ecosistema y lanzamiento de mini programas | ✅ | +| [Avanzado 4: Mini Program con Back-end](../../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | Lógica de negocio completa en mini programas | 🚧 | +| [Avanzado 5: Android App Development](../../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Desarrollo unificado con Expo | ✅ | +| [Avanzado 6: iOS App Development](../../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Desarrollo unificado con Expo | ✅ | +| [Avanzado 7: Web personal y blog académico](../../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | Construcción de marca personal en línea | 🚧 | + +
+ +## 🛠️ Cómo aprender + +- Según tu nivel, elige los capítulos relevantes para leer y practicar. + +## 💻 Configuración local + +### Método moderno + +En tu AI IDE (VS Code, Cursor, Trae), usa el siguiente prompt: ``` -Por favor ayúdame a ejecutar el servicio local de este proyecto +Por favor, ayúdame a ejecutar el servicio local de este proyecto. ``` -### Método Antiguo +### Método tradicional 1. npm install 2. npm run dev -3. Abre tu navegador y visita `http://localhost:3000` para ver. +3. Abre `http://localhost:3000` en tu navegador. ## 🤝 Contribuir -- Si descubres algún problema, o crees que hay algo que se pueda mejorar en este proyecto, puedes enviar un Issue para dar feedback. Si después de enviar nadie responde, puedes contactar al [equipo de cuidadores](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) para feedback y seguimiento~ -- Si quieres contribuir a este proyecto, puedes enviar un Pull Request, si después de enviar nadie responde, puedes contactar al [equipo de cuidadores](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) para feedback y seguimiento~ -- Si estás muy interesado en Datawhale y quieres iniciar un nuevo proyecto, por favor sigue la [guía de proyectos de código abierto de Datawhale](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)~ +- Si encuentras problemas, por favor abre un Issue. +- Si quieres contribuir, envía un Pull Request. -## 🙏 Gracias a Cada Contribuyente +## 🙏 Agradecimientos -- [散步-Líder del proyecto](https://github.com/sanbuphy) (Miembro de Datawhale) -- Fang Ke-Profesor guía (Miembro de Datawhale, Universidad de Tsinghua) -- [Yerim Kang](https://github.com/yerim25)（Parte de proyectos prácticos-Universidad de Tsinghua） -- Zhao Zhilin（Parte de proyectos prácticos-Universidad de Tsinghua） -- [Li Yixuan](https://yixuan20.github.io/)（Diseño artístico de página-Universidad de Tsinghua） -- Todos los compañeros del grupo beta de AI Vibe Coding 101 que proporcionaron sugerencias y experiencia +- [Sanbu - Líder del proyecto](https://github.com/sanbuphy) (Miembro de Datawhale) +- Fang Ke - Asesor (Miembro de Datawhale, Univ. de Tsinghua) +- Todo el equipo de diseño y pruebas por su apoyo ❤️ -### Agradecimientos Especiales +
-- Gracias a [@Sm1les](https://github.com/Sm1les) por su ayuda y apoyo a este proyecto -- Gracias a todos los desarrolladores que han contribuido a este proyecto ❤️ +

+ Stargazers +    + Forkers +

+ + + + + + + +
@@ -201,13 +359,13 @@ Por favor ayúdame a ejecutar el servicio local de este proyecto
-## 📧 Contáctanos +## 📧 Contacto
-

Si tienes preguntas, sugerencias, quejas, o quieres comunicarte, por favor escanea el código QR a continuación

- +

Si tienes sugerencias o quieres colaborar, escanea el código QR:

+ -

Escanea el código QR a continuación para seguir la cuenta oficial: Datawhale

+

Sigue a Datawhale en WeChat:

@@ -216,16 +374,16 @@ Por favor ayúdame a ejecutar el servicio local de este proyecto
Licencia Creative Commons
-Este trabajo está licenciado bajo una +Este trabajo está bajo una Licencia Creative Commons Atribución-NoComercial-CompartirIgual 4.0 Internacional - +.
## Star History diff --git a/docs-readme/fr-FR/README.md b/docs-readme/fr-FR/README.md index 75d7d6c..09db699 100644 --- a/docs-readme/fr-FR/README.md +++ b/docs-readme/fr-FR/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _De zéro, apprentissage par projet, construire votre premier produit IA_ +# Easy-Vibe : Apprendre le Vibe Coding de 0 à 1

- 📌 Commencer la lecture en ligne (Start Reading Online) + 📌 Lire en ligne (Read Online) · ✨ Tutoriel interactif

Lire en ligne · - Carte d'apprentissage · + Carte d'apprentissage · Communauté

@@ -38,196 +36,42 @@ English 日本語 Español - Français + Français + Klingon 한국어 العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

+ + + + + +
+ +
+ Carte d'apprentissage exclusive pour débutants +
+ Guidage à partir de zéro, planification claire, dites adieu à "apprendre et oublier" + 		+ +
+ Tutoriel graphique pas à pas +
+ Explications détaillées, comme un tuteur privé à vos côtés +
-## 🚀 Présentation du Projet +À l'ère de l'IA, les personnes qui transforment les idées en produits sont souvent celles qui font le premier pas. **Easy-Vibe est né pour cela.** -Quand vous essayez d'écrire du code avec l'IA, vous rencontrez des erreurs constantes, vous voulez souvent abandonner et il n'est pas clair comment mettre réellement vos programmes en ligne 😢. +| Étape | Compétences clés | Résultat | +| ------------ | -------------------------------- | ----------------------------------------- | +| **É tape 1** | Intro programmation IA, pensée produit | Mini-jeux, prototypes Web (Débutant & PM) | +| **Étape 2** | Développement Full-stack, IA, Bases de données | Application IA Full-stack complète | +| **Étape 3** | Claude Code avancé, Mobiles & Mini-progs | Applications multiplateformes niveau production | -Ce tutoriel est spécialement conçu pour vous mener de 0 à 1, maîtrisant progressivement les techniques de Vibe Coding : - -- **Étape 1** : Des **mini-jeux aux prototypes web**, maîtriser les bases de la programmation IA et la pensée produit -- **Étape 2** : Apprendre le **développement frontend/backend et les capacités d'IA** liées aux techniques de Vibe Coding, compléter une application complète -- **Étape 3** : Maîtriser la construction d'**applications complexes multiplateformes**, vers des applications de niveau production - -Nous croyons qu'en maîtrisant Vibe Coding et en le combinant avec un entraînement systématique, une seule personne peut devenir un développeur combinant développement frontend, développement backend, intégration de capacités d'IA et conception de produits. - -> **Ce projet s'adresse principalement à trois types d'apprenants :** -> -> - **Débutants (gens ordinaires / produit et opérations)** : Aider les apprenants non techniques à comprendre les concepts clés et à compléter leur premier prototype de produit -> - **Développeurs de niveau débutant-intermédiaire (étudiants et développeurs avec une certaine base)** : Maîtriser les connaissances de Vibe Coding frontend/backend et les capacités d'IA -> - **Développeurs avancés (entreprises et startups, open source et développeurs indépendants)** : Techniques de développement avancées, développement multiplateforme - -### 📖 Navigation du Contenu - -
- Learning Map -
- -### Annexe Générale - -[Dictionnaire des capacités IA : concepts centraux IA courants, termes et explications de scénarios](docs/zh-cn/appendix/ai-capability-dictionary.md) - -### 1. Entrée débutant et prototype de produit - -| Chapitre | Contenu clé | Statut | -| :--------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----- | -| [Préface : Carte d'apprentissage](docs/zh-cn/stage-0/0.1-learning-map/index.md) | Guide général du parcours d'apprentissage | ✅ | -| [Débutant 1 : L'ère de l'IA, savoir parler c'est savoir programmer](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Découvrir pour la première fois les capacités de programmation IA à travers des cas comme Snake | ✅ | -| [Débutant 2 : Découvrir les outils IDE IA](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | Apprendre à utiliser l'IDE, créer des mini-jeux localement | ✅ | -| [Débutant 3 : Créer un prototype soi-même](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | Analyse des besoins, génération d'une seule page par l'IA, jusqu'à générer des prototypes de produits multipages | ✅ | -| [Débutant 4 : Ajouter des capacités IA au prototype](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Apprendre à connecter des capacités IA courantes (texte, image, vidéo) | ✅ | -| [Débutant 5 : Projet complet pratique](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Simuler des scénarios réels, accepter les feedbacks des utilisateurs pour itérer, compléter le projet | ✅ | -| [Projet final : Créer un prototype complet d'application web et le présenter](docs/zh-cn/stage-1/1.5-final-project/index.md) | Implémenter complètement l'application, présenter les effets de l'application | ✅ | - -#### Annexes : Pensée Business - -| Chapitre | Contenu clé | Statut | -| :------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :----- | -| [Annexe A : Pensée Produit et Conception de Solution](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Cadres de pensée nécessaires pour créer un produit de zéro à un | ✅ | -| [Annexe B : Référence des Scénarios d'Application AI dans l'Industrie (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | Comprendre les applications AI dans différentes industries | ✅ | -| [Annexe C : Référence d'Inspiration des Scénarios de Consommation AI (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | Explorer les applications AI dans les produits grand public | ✅ | - -#### Annexes : Solutions Techniques - -| Chapitre | Contenu clé | Statut | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------- | :----- | -| [Annexe D : Que Faire en Cas d'Erreur lors de l'Écriture de Code](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Erreurs courantes en Vibe Coding et méthodes de dépannage | ✅ | -| [Annexe E : Comparaison de 7 Outils de Programmation AI](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | Comparer et tester les principales plateformes de programmation AI | ✅ | -| [Annexe F : Concevoir des Sites Web avec des Agents de Design et de Programmation](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Apprendre à utiliser les agents AI de manière collaborative | ✅ | - -### 2. Ingénieur de Développement Niveau Débutant-Intermédiaire - -#### Partie Frontend - -| Chapitre | Contenu clé | Statut | -| :----------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | -| [Frontend 0 : Utiliser lovart pour générer des assets](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Utiliser lovart pour générer en lot des assets visuels comme des personnages et des scènes, fournissant une base d'assets pour la conception UI et le développement frontend | 🚧 | -| [Frontend 1 : Introduction à Figma et MasterGo](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | Utiliser des outils de conception pour organiser l'architecture de l'information et la structure des pages, préparant la base pour l'implémentation frontend | 🚧 | -| [Frontend 2 : Construire la première application moderne - Design UI](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | Compléter une interface basée sur des composants à partir de maquettes, réaliser le premier parcours du design au code | 🚧 | -| [Frontend 3 : Référence des spécifications de design UI et design UI multiproduit](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | Étendre des interfaces multiproduits autour d'une visuelle principale unifiée, pratiquer les capacités de design systématique | 🚧 | -| [Frontend 4 : Créons ensemble les portraits de Poudlard](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | Créer une application frontend avec capacités IA intégrées de 0 à 1, connecter conception et développement | ✅ | - -#### Partie Backend et Full Stack - -| Chapitre | Contenu clé | Statut | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----- | -| [Backend 1 : Qu'est-ce qu'une API](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | Comprendre les interfaces HTTP et les modèles requête-réponse, se préparer à l'intégration backend et à la coordination | ✅ | -| [Backend 2 : Des bases de données à Supabase](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) : Implémenter des bases de données et des APIs sur Supabase, connecter des modèles de données aux pages frontend | ✅ | -| [Backend 3 : LLM assistant l'écriture de code d'interface et de documentation](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) : Utiliser le LLM pour aider à générer de la documentation et du code pour les interfaces et bases de données, réaliser un backend lisible et testable | 🚧 | -| [Backend 4 : Flux de travail Git](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) : Gérer le code dans un flux de travail Git, effectuer le contrôle de version et la collaboration | ✅ | -| [Backend 5 : Déploiement Zeabur](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) : Déployer l'application sur Zeabur pour la mettre en ligne | ✅ | -| [Backend 6 : Outils de développement CLI modernes](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) : Utiliser des outils de programmation IA de type CLI pour accélérer le développement et le débogage, former un flux d'ingénierie personnel | ✅ | -| [Backend 7 : Comment intégrer des systèmes de paiement comme Stripe](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) : Connecter des systèmes de paiement, compléter le flux de paiement et le processus de base de règlement | 🚧 | -| [Projet final 1 : Construire la première application moderne - Application full stack](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) : Intégrer frontend, backend et modules de paiement, compléter une application web full stack prête pour la production | 🚧 | -| [Projet final 2 : Bibliothèque de composants frontend moderne + Trae pratique](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) : Utiliser une bibliothèque de composants frontend moderne et Trae, compléter indépendamment un produit avec inscription/connexion et support de paiement | 🚧 | - -#### Annexe des Capacités IA - -| Chapitre | Contenu clé | Statut | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- | :----- | -| [IA 1 : Introduction à Dify et intégration de base de connaissances](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) : Utiliser Dify Workflow et le RAG de base pour construire des produits de type outils, créant un exemple pour les futures mises à jour d'applications | ✅ | -| [IA 2 : Apprendre à consulter le dictionnaire IA et intégrer des APIs multimodales](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) : Apprendre à chercher des modèles et APIs appropriés, intégrer des capacités multimodales comme le texte et l'image dans des produits | 🚧 | - -### 3. Ingénieur de Développement Avancé - -| Chapitre | Contenu clé | Statut | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- | :----- | -| [Avancé 1 : MCP et Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) : Étendre les capacités de l'IDE via MCP et Skills, connecter des services externes comme outils | 🚧 | -| [Avancé 2 : Comment faire fonctionner Coding Tools longtemps](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) : Concevoir et configurer des tâches à longue exécution, rendre Coding Tools plus stable et fiable | 🚧 | -| [Avancé 3 : Développement multiplateforme : Comment construire des mini-programmes WeChat](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) : Comprendre l'écosystème des mini-programmes WeChat, compléter un mini-programme frontend du modèle officiel au lancement | ✅ | -| [Avancé 4 : Développement multiplateforme : Comment construire des mini-programmes WeChat - Y compris backend](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) : Intégrer une base de données et une logique backend dans les mini-programmes, réaliser un cycle d'activité complet | 🚧 | -| [Avancé 5 : Développement multiplateforme : Comment construire des applications Android](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) : Utiliser des outils comme Expo, compléter le développement d'applications Android intégrant Web natif | 🚧 | -| [Avancé 6 : Développement multiplateforme : Comment construire des applications iOS](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) : Utiliser des outils comme Expo, compléter le développement d'applications iOS intégrant Web natif | 🚧 | -| [Avancé 7 : Comment construire son propre site web personnel et blog académique](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) : Du choix, de la construction au déploiement, construire une homepage en ligne à long terme présentant des projets personnels et des réalisations académiques | 🚧 | - -#### Annexe des Capacités IA - -| Chapitre | Contenu clé | Statut | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | :----- | -| [IA Avancée 1 : Qu'est-ce que RAG et comment il fonctionne](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) : Comprendre systématiquement les principes du RAG et les architectures courantes, fournir une base de récupération de connaissances pour des applications complexes | ✅ | -| [IA Avancée 2 : RAG intermédiaire-avancé et orchestration de workflows : Exemple avec LangGraph](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) : Utiliser des outils comme LangGraph pour concevoir des workflows multi-étapes et des systèmes RAG intermédiaire-avancés | 🚧 | - -## 🛠️ Comment Apprendre - -- Selon vos capacités personnelles, lisez et pratiquez sélectivement les chapitres pertinents, si vous avez des questions posez-les dans des Issues. - -## 💻 Démarrer Ce Cours Localement - -### Méthode Moderne - -Dans la boîte de dialogue de l'IDE IA (vscode, cursor, trae, etc.), entrez le prompt suivant pour démarrer ce cours : - -``` -S'il vous plaît aidez-moi à exécuter le service local de ce projet -``` - -### Ancienne Méthode - -1. npm install -2. npm run dev -3. Ouvrez votre navigateur et visitez `http://localhost:3000` pour voir. - -## 🤝 Contribuer - -- Si vous découvrez des problèmes, ou pensez qu'il y a des moyens d'améliorer ce projet, vous pouvez soumettre une Issue pour donner un feedback. Si après soumission personne ne répond, vous pouvez contacter l'[équipe des soignants](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) pour un suivi~ -- Si vous souhaitez contribuer à ce projet, vous pouvez soumettre une Pull Request, si après soumission personne ne répond, vous pouvez contacter l'[équipe des soignants](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) pour un suivi~ -- Si vous êtes très intéressé par Datawhale et souhaitez lancer un nouveau projet, veuillez suivre le [guide de projets open source Datawhale](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)~ - -## 🙏 Merci à Chaque Contributeur - -- [散步-Chef de projet](https://github.com/sanbuphy) (Membre Datawhale) -- Fang Ke-Professeur guide (Membre Datawhale, Université Tsinghua) -- [Yerim Kang](https://github.com/yerim25)（Partie projets pratiques-Université Tsinghua） -- Zhao Zhilin（Partie projets pratiques-Université Tsinghua） -- [Li Yixuan](https://yixuan20.github.io/)（Design artistique de page-Université Tsinghua） -- Tous les camarades du groupe bêta AI Vibe Coding 101 qui ont fourni des suggestions et de l'expérience - -### Remerciements Spéciaux - -- Merci à [@Sm1les](https://github.com/Sm1les) pour son aide et son soutien à ce projet -- Merci à tous les développeurs qui ont contribué à ce projet ❤️ - -
- - - -
- -## 📧 Contactez-nous - -
-

Si vous avez des questions, des suggestions, des plaintes, ou souhaitez échanger, veuillez scanner le code QR ci-dessous

- - -

Scannez le code QR ci-dessous pour suivre le compte officiel : Datawhale

- -
- -## 📄 LICENCE - -
- - Licence Creative Commons - -
-Ce travail est sous licence - - Licence Creative Commons Attribution - Pas d'Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International - -
- -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=datawhalechina/easy-vibe&type=date&legend=top-left)](https://www.star-history.com/#datawhalechina/easy-vibe&type=date&legend=top-left) +*(Voir les détails dans les autres langues ou le dépôt principal)* diff --git a/docs-readme/ja-JP/README.md b/docs-readme/ja-JP/README.md index 427eda6..370be79 100644 --- a/docs-readme/ja-JP/README.md +++ b/docs-readme/ja-JP/README.md @@ -4,17 +4,15 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _ゼロから、プロジェクトベース学習、最初の AI 製品を構築_ +# Easy-Vibe : 0から1で学ぶVibe Coding

- 📌 オンラインで読み始める (Start Reading Online) + 📌 オンラインで読む (Read Online) · ✨ インタラクティブチュートリアル

@@ -36,164 +34,347 @@ 简体中文 繁體中文 English - 日本語 + 日本語 Español Français + Klingon 한국어 العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

+ + + + + + + + + + + + + +
+ +
+ 初心者のための学習マップ +
+ ゼロベースのガイド、明確なパス設計、「学んで忘れる」からの脱却 + 		+ +
+ ステップバイステップの図解チュートリアル +
+ 丁寧な図解解説、まるで専属講師がついているかのように進められます +
+ +
+ 没入型シミュレーションプログラミング +
+ 仮想マウスによる自動ナビゲーションで、IDEのコアな使い方を素早く習得 + 		+ +
+ 「見える」AI原理 +
+ アルゴリズムの原理をアニメーション化、AIがいかにして画像を「描く」のかを一目で理解 +
+ +
+ ゲームのようにRAGを学ぶ +
+ 独自の対話型コンポーネントで、クリックするだけでRAGのデータフローを明確に確認 + 		+ +
+ 可視化されたターミナルの原理 +
+ コマンドライン操作を可視化し、バックエンドのロジックと原理を直感的に表示 +
+
+

⭐ こちらからStar を追加して更新を応援してください ❤️

+
-## 🚀 プロジェクト紹介 +AI時代、アイデアを製品に変える人は、必ずしも技術が最も強い人ではなく、最初に行動を起こした人です。 -AI でコードを書こうとしてエラーが続き、諦めかけたくなり、プログラムを本当にオンラインにする方法がわからないとき 😢 +AIアシスタントがいても、「コードが読めない」「環境構築ができない」と諦めてしまう人が多くいます。**Easy-Vibeはそのために生まれました。** 全員がゼロベースであることを前提に、最初の一行のコードから、前後端のロジックの理解、そして最終的な製品のリリースまで、手取り足取りガイドします。 -本チュートリアルは、0 から 1 まで、Vibe Coding のスキルを段階的に習得できるように設計されています： +- **対象者**: 初心者、プロダクトマネージャー、フロントエンド/バックエンド/フルスタックエンジニア +- **テーマ**: AIプログラミング、フルスタックWebアプリ開発、AI Agent、ワークフロー、RAGシステム -- **第 1 段階**：**ミニゲームからWeb プロトタイプまで**、AI プログラミングの基礎とプロダクト思考を習得 -- **第 2 段階**：**フロントエンド・バックエンド開発と AI 能力**に関連する Vibe Coding テクニックの学習、完全なアプリケーションの完成 -- **第 3 段階**：**マルチプラットフォーム複雑アプリケーション**の構築手法を習得、本番級アプリケーションへ +--- -私たちは、Vibe Coding を習得し体系的なトレーニングを組み合わせることで、一人でフロントエンド開発、バックエンド開発、AI 能力統合、プロダクトデザインを兼ね備えた開発者になれると信じています。 +Easy-Vibeは以下の段階を経て、あなたを0から1へと導きます： -> **本プロジェクトは主に 3 種類の学習者を対象としています：** -> -> - **初心者（一般人 / プロダクト・運用担当者）**：非技術系初心者が重要な概念を理解し、最初のプロダクトプロトタイプを完成させるのを支援 -> - **初中級開発者（一定の基礎がある学生と開発者）**：フロントエンド・バックエンドの Vibe Coding と AI 能力の知識を習得 -> - **上級開発者（企業・スタートアップ、オープンソース・独立開発者）**：高度な開発技術、マルチプラットフォーム開発 +| ステージ | コアスキル | 成果物 | +| ------------ | -------------------------------- | ----------------------------------------- | +| **第一段階** | AIプログラミング入門、プロダクト思考、プロトタイプ設計 | インタラクティブゲーム、Webアプリのプロトタイプ (初心者 & PM) | +| **第二段階** | フルスタック開発、AI統合、データベース | 完全なフルスタックAIアプリケーション | +| **第三段階** | Claude Code活用、ミニプログラム・Android開発 | 本番級のマルチプラットフォームアプリケーション | +| **付録** | コンピュータとAIの基礎概念の理解を支援 | 9大知識領域、80以上のインタラクティブ特集 | + +## 🔥 News + +- **[2026-02-25]** [付録知識ベース](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/)を更新。9大知識領域、80以上のインタラクティブ特集を網羅。 +- **[2026-01-27]** AndroidおよびiOSプラットフォームのアプリ開発チュートリアルを追加。 +- **[2026-01-19]** Prompt Engineering、AIの進化史、認証設計、Gitの原理などの一連のインタラクティブ・デモ・コンポーネントをリリース。 + +
+Past News + +- **[2026-01-16]** プロジェクト構造を再構築し、初心者のハードルを下げるための「初心者入門」の章を正式に確立。 +- **[2026-01-14]** 第一段階「製品プロトタイプの構築」ドキュメントの大規模な更新を完了。 +- **[2026-01-13]** ドキュメントアーキテクチャの再構築を完了し、多言語(i18n)を全面的にサポート。 +- **[2026-01-01]** プロジェクトのコア学習マップ (Learning Map) をリリースし、学習パスを明確化。 +
### 📖 コンテンツナビゲーション
- Learning Map + Learning Map
-### 総付録 +### 📚 付録知識ベース -[AI 能力辞書：一般的な AI コア概念と用語、シーンの解釈](docs/zh-cn/appendix/ai-capability-dictionary.md) +> **9大知識領域**、**80以上のインタラクティブ特集**を網羅し、アニメーションと可視化コンポーネントを通じて、コンピュータの低層からAIの最前線までのコア概念を直感的に理解するのを助けます。 +> +> 👉 [完全な付録を表示](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) · [AI能力辞書](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary) -### 一、初心者入門とプロダクトプロトタイプ + + + + + + + + + + + + + + + + +
+ 💻 コンピュータ基礎

+ • トランジスタからCPUへ
+ • オペレーティングシステム
+ • データのエンコード・保存・伝送
+ • ネットワーク：二台のPCはどう対話するか
+ • データ構造
+ • アルゴリズム思考入門 + 		+ 🔧 開発ツール

+ • Git：コードのタイムマシン
+ • コマンドラインとShellスクリプト
+ • パッケージマネージャー
+ • デバッグの芸術
+ • 正規表現
+ • 環境変数とPATH + 		+ 🌐 ブラウザとフロントエンド

+ • JavaScript言語の深掘り
+ • ブラウザレンダリングパイプライン
+ • フロントエンドフレームワークの比較
+ • グラフィックスとアニメーション
+ • Webパフォーマンスの測定と最適化
+ • フロントエンドエンジニアリングの全貌 +
+ 🖥️ サーバーとバックエンド

+ • HTTPプロトコル
+ • API設計の哲学
+ • 認証と認可の体系
+ • 並行・非同期・マルチスレッド
+ • メッセージキューとイベント駆動
+ • バックエンド階層構造 + 		+ 📊 データ

+ • SQL
+ • データベース原理
+ • データトラッキングとユーザー行動収集
+ • データ分析の基礎
+ • A/Bテストと実験駆動
+ • データの可視化とダッシュボード + 		+ 🏗️ アーキテクチャとシステム設計

+ • モノリスからマイクロサービスへの進化
+ • 分散システムの課題
+ • 高可用性と災害復旧
+ • システム設計メソッドロジー +
+ ☁️ インフラと運用

+ • Dockerコンテナ化
+ • Kubernetesオーケストレーション
+ • CI / CDオートメーション
+ • ドメイン、DNS、HTTPS
+ • モニタリング、ログ、アラート
+ • Infrastructure as Code (IaC) + 		+ 🤖 人工知能

+ • 大規模言語モデルの仕組み
+ • Transformerとアテンション機構
+ • RAGアーキテクチャ
+ • AI Agentとツール呼び出し
+ • プロンプトエンジニアリング
+ • 画像生成の原理 + 		+ 🎯 エンジニアの素養

+ • コード品質とリファクタリング
+ • テスト戦略
+ • デザインパターン
+ • セキュリティ思考と攻防の基礎
+ • 技術ドキュメントの作成
+ • オープンソースでの協力 +
-| 章 | 主要内容 | 状態 | -| :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :--- | -| [前書：学習マップ](docs/zh-cn/stage-0/0.1-learning-map/index.md) | 全体学習パスのガイド | ✅ | -| [初級一：AI 時代、話せるだけでプログラミングできる](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | スネークゲームなどの事例を通じて AI プログラミングの能力を初めて体験 | ✅ | -| [初級二：AI IDE ツールを知る](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | IDE の使用方法を学び、ローカルでミニゲームを作成 | ✅ | -| [初級三：手を動かしてプロトタイプを作る](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | ニーズ分析、AI による単一ページ生成、複数ページプロダクトプロトタイプの生成へ | ✅ | -| [初級四：プロトタイプに AI 能力を追加](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | 一般的な AI 能力（テキスト、画像、動画）の接続方法を習得 | ✅ | -| [初級五：完全プロジェクト実戦](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 実際のシーンをシミュレート、ユーザーフィードバックを受け反復改良、プロジェクトを完全に | ✅ | -| [大課題：完全な Web アプリケーションプロトタイプを作成し展示](docs/zh-cn/stage-1/1.5-final-project/index.md) | アプリケーションを完全に実装し、アプリケーション効果を展示 | ✅ | +### 一、ゼロからの入門 + +| 章 | 主要な内容 | 状態 | +| :----------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | +| [前書き：学習マップ](../../docs/zh-cn/stage-0/0.1-learning-map/index.md) | 全体的な学習パスのナビゲーション | ✅ | +| [初級一：AI時代、「話す」ことがプログラミングになる](../../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | スネークゲームなどの事例を通じてAIプログラミングの能力を体験 | ✅ | +| [初級二：良いアイデアを探す](../../docs/zh-cn/stage-1/1.0-finding-great-idea/index.md) | 製品のアイデアを探し、検証し、価値のあるプロジェクトを見つける方法を学ぶ | ✅ | +| [初級三：AI IDEツールを知る](../../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | IDEの使い方を学び、ローカルでミニゲームを作成 | ✅ | +| [初級四：プロトタイプを自作する](../../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | 要件分析からAIによる単一ページ生成、そして複数ページの製品プロトタイプへ | ✅ | +| [初級五：プロトタイプにAI能力を加える](../../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | 一般的なAI能力（テキスト、画像、動画）の連携方法を学ぶ | ✅ | +| [初級六：プロジェクトの実践](../../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 実際のシーンをシミュレートし、ユーザーからのフィードバックを受けてプロジェクトを完成させる | ✅ | #### 付録：ビジネス思考 -| 章 | 主要内容 | 状態 | -| :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | -| [付録 A：プロダクト思考とソリューション設計](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | ゼロからイチまでプロダクトを作る際に必要な思考フレームワーク | ✅ | -| [付録 B：AI 業界アプリケーションシナリオ参考 (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | さまざまな業界での AI 応用事例を理解する | ✅ | -| [付録 C：AI 消費シナリオインスピレーション参考 (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | 消費者向け製品での AI 応用事例を探索する | ✅ | +| 章 | 主要な内容 | 状態 | +| :----------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [付録A：プロダクト思考とソリューション設計](../../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | 製品をゼロから作る際に考慮すべき思考フレームワーク | ✅ | +| [付録B：AI業界の活用シーン参考 (B向け)](../../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | さまざまな業界におけるAIの活用シーンを理解する | ✅ | +| [付録C：AIコンシューマー向けシーンのインスピレーション (C向け)](../../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | コンシューマー向け製品におけるAIの活用シーンを探求する | ✅ | #### 付録：技術ソリューション -| 章 | 主要内容 | 状態 | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- | -| [付録 D：コード作成時にエラーが発生した場合の対処法](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Vibe Coding における一般的なエラーとトラブルシューティング方法 | ✅ | -| [付録 E：7 つの AI プログラミングツール比較](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 主流の AI プログラミングプラットフォームの比較テスト | ✅ | -| [付録 F：デザインとプログラミングエージェントでウェブサイトを設計](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | AI エージェントの協調的な使用方法を学ぶ | ✅ | +| 章 | 主要な内容 | 状態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [付録D：エラーに遭遇した時の対処法](../../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | vibe codingにおける一般的なエラーとその調査方法 | ✅ | +| [付録E：AIプログラミングツール7選の比較](../../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 主要なAIプログラミングプラットフォームの比較テスト | ✅ | +| [付録F：デザインとプログラミングAgentによるサイト設計](../../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | AIエージェントとの協調作業の方法を学ぶ | ✅ | -### 二、初中級開発エンジニア +
+二、初・中級エンジニア -#### フロントエンド部分 +#### フロントエンド -| 章 | 主要内容 | 状態 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :--- | -| [フロントエンド零：lovart を使用して素材を生成](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | lovart を使ってキャラクター、シーンなどの視覚素材を一括生成し、UI デザインとフロントエンド開発に素材基盤を提供 | 🚧 | -| [フロントエンド一：Figma と MasterGo 入門](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | デザインツールを使って情報アーキテクチャとページ構造を整理し、フロントエンド実装の基礎を築く | 🚧 | -| [フロントエンド二：最初のモダンアプリケーションを構築 - UI デザイン](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | デザイン画に基づいてコンポーネント化インターフェースを完成させ、デザインからコードへの最初のパスを実現 | 🚧 | -| [フロントエンド三：UI デザイン仕様とマルチプロダクト UI デザインを参照](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 統一されたメインビジュアルを中心にマルチプロダクトインターフェースを拡張し、体系的デザイン能力を練習 | 🚧 | -| [フロントエンド四：一緒にハリー・ポッターの肖像画を作ろう](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | 0 から 1 まで AI 能力を統合したフロントエンドアプリケーションを作成し、デザインと開発を接続 | ✅ | +| 章 | 主要な内容 | 状態 | +| :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | +| [フロントエンド0：Lovartを使用した素材生成](../../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | Lovartを使用してキャラクターや背景などのビジュアル素材を一括生成する方法を学ぶ | 🚧 | +| [フロントエンド1：FigmaとMasterGo入門](../../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | 設計ツールを使用して情報アーキテクチャとページ構造を整理する | 🚧 | +| [フロントエンド2：最初の現代的アプリケーションの構築 - UIデザイン](../../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | デザイン案に基づいたコンポーネント化されたインターフェースの完成 | 🚧 | +| [フロントエンド3：UIデザイン仕様とマルチプロダクトUI設計](../../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 統一されたメインビジュアルを中心に、システム化されたデザイン能力を磨く | 🚧 | +| [フロントエンド4：ホグワーツの肖像画を一緒に作る](../../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | AI能力を組み込んだフロントエンドアプリをゼロから作成 | ✅ | -#### バックエンドとフルスタック部分 +#### バックエンドとフルスタック -| 章 | 主要内容 | 状態 | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :--- | -| [バックエンド一：API とは](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTP インターフェースとリクエスト・レスポンスモデルを理解し、バックエンド統合と連携調整の準備 | ✅ | -| [バックエンド二：データベースから Supabase へ](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Supabase 上でデータベースと API を実装し、データモデルとフロントエンドページを接続 | ✅ | -| [バックエンド三：大規模言語モデル支援によるインターフェースコードとドキュメント作成](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | 大規模言語モデルを使ってインターフェースとデータベースのドキュメントおよびコードの生成を支援し、読みやすくテスト可能なバックエンドを実現 | 🚧 | -| [バックエンド四：Git ワークフロー](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Git ワークフローでコードを管理し、バージョン管理とコラボレーションを行う | ✅ | -| [バックエンド五：Zeabur デプロイ](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | アプリケーションを Zeabur にデプロイしてオンライン化 | ✅ | -| [バックエンド六：モダン CLI 開発ツール](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | CLI 系 AI プログラミングツールを使用して開発とデバッグを加速し、個人のエンジニアリングワークフローを形成 | ✅ | -| [バックエンド七：Stripe などの課金システムの統合方法](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 決済システムを接続し、課金パスと基本決済フローを完成 | 🚧 | -| [大課題 1：最初のモダンアプリケーションを構築 - フルスタックアプリ](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | フロントエンド、バックエンド、決済モジュールを統合し、オンライン可能なフルスタック Web アプリケーションを完成 | 🚧 | -| [大課題 2：モダンフロントエンドコンポーネントライブラリ + Trae 実戦](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | モダンフロントエンドコンポーネントライブラリと Trae を使用し、ログイン・登録可能で課金対応のプロダクトを独立完成 | 🚧 | +| 章 | 主要な内容 | 状態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | +| [バックエンド1：APIとは何か](../../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTPインターフェースとリクエスト・レスポンスモデルの理解 | ✅ | +| [バックエンド2：データベースからSupabaseへ](../../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Supabase上でのデータベースとAPIの実装 | ✅ | +| [バックエンド3：大規模言語モデルによるインターフェースコードとドキュメントの生成](../../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | ドキュメントとコードの生成をAIで支援 | 🚧 | +| [バックエンド4：Gitワークフロー](../../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Gitワークフローでのコード管理、バージョン管理と協力 | ✅ | +| [バックエンド5：Zeaburへのデプロイ](../../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | アプリケーションをZeaburにデプロイして公開 | ✅ | +| [バックエンド6：現代的なCLI開発ツール](../../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | CLIツールによる開発とデバッグの加速 | ✅ | +| [バックエンド7：Stripeなどの決済システムの統合方法](../../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 決済システムを導入し、収益化の仕組みを完成させる | 🚧 | +| [課題1：最初の現代的アプリケーション - フルスタックアプリ](../../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | フロントエンド、バックエンド、決済モジュールの統合 | 🚧 | +| [課題2：現代的フロントエンドコンポーネントライブラリ + Trae実践](../../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | ログイン、登録、決済をサポートする製品の独立開発 | 🚧 | -#### AI 能力付録 +#### AI能力付録 -| 章 | 主要内容 | 状態 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- | :--- | -| [ AI 一：Dify 入門とナレッジベース統合](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify Workflow と基本 RAG を使ってツール系プロダクトを構築し、以降のアプリケーションアップグレードのモデルケースを作成 | ✅ | -| [ AI 二：AI 辞典の検索とマルチモーダル API 統合を学ぶ](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 適切なモデルと API を検索する方法を学び、テキスト、画像などのマルチモーダル能力をプロダクトに統合 | 🚧 | +| 章 | 主要な内容 | 状態 | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- | +| [AI一：Dify入門と知識ベースの統合](../../docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify Workflowと基礎的なRAGを使用したツールの構築 | ✅ | +| [AI二：AI辞書の引き方とマルチモーダルAPIの統合](../../docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 適切なモデルとAPIの探し方、それらの統合方法を学ぶ | 🚧 | -### 三、上級開発エンジニア +
-| 章 | 主要内容 | 状態 | -| :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :--- | -| [上級一：MCP と Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | MCP と Skills を通じて IDE 能力を拡張し、外部サービスをツールとして接続 | 🚧 | -| [上級二：Coding Tools を長時間動作させる方法](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 長時間動作するタスクを設計・設定し、Coding Tools をより安定して信頼性の高いものに | 🚧 | -| [上級三：マルチプラットフォーム開発：WeChat ミニプログラムの構築方法](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | WeChat ミニプログラムのエコシステムを理解し、公式テンプレートからリリースまでフロントエンドミニプログラムを完成 | ✅ | -| [上級四：マルチプラットフォーム開発：WeChat ミニプログラムの構築方法 - バックエンド含む](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | ミニプログラムにデータベースとバックエンドロジックを統合し、完全な業務クローズドループを実現 | 🚧 | -| [上級五：マルチプラットフォーム開発：Android アプリの構築方法](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Expo などのツールを使用し、Web/ネイティブ一体化の Android アプリ開発を完成 | 🚧 | -| [上級六：マルチプラットフォーム開発：iOS アプリの構築方法](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Expo などのツールを使用し、Web/ネイティブ一体化の iOS アプリ開発を完成 | 🚧 | -| [上級七：自分専用の個人ウェブページと学術ブログの構築方法](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 選定、構築からデプロイまで、個人プロジェクトと学術成果を展示する長期的なオンラインホームページを構築 | 🚧 | +
+三、上級エンジニア -#### AI 能力付録 +| 章 | 主要な内容 | 状態 | +| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | +| [上級一：MCPとClaude Code Skills](../../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | MCPとSkillsによるIDE能力の拡張 | 🚧 | +| [上級二：Coding Toolsを長時間稼働させる方法](../../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 長時間実行されるタスクの設計と構成 | 🚧 | +| [上級三：マルチプラットフォーム開発：WeChatミニプログラムの構築](../../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | WeChatミニプログラムのエコシステムと開発フロー | ✅ | +| [上級四：マルチプラットフォーム開発：バックエンドを含むWeChatミニプログラム](../../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | ミニプログラムへのデータベースとバックエンドロジックの導入 | 🚧 | +| [上級五：マルチプラットフォーム開発：Androidアプリの構築](../../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Expoなどのツールを使用したAndroidアプリ開発 | ✅ | +| [上級六：マルチプラットフォーム開発：iOSアプリの構築](../../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Expoなどのツールを使用したiOSアプリ開発 | ✅ | +| [上級七：自分だけの個人ページと学術ブログの構築](../../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 技術選定から構築、デプロイまでを網羅 | 🚧 | -| 章 | 主要内容 | 状態 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :--- | -| [上級 AI 一：RAG とは、それがどのように動作するか](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 原理と一般的なアーキテクチャを体系的に理解し、複雑なアプリケーションに知識検索基盤を提供 | ✅ | -| [上級 AI 二：中上級 RAG とワークフロー編成：LangGraph を例に](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | LangGraph などのツールを使用してマルチステップワークフローと中上級 RAG システムを設計 | 🚧 | +#### AI能力付録 + +| 章 | 主要な内容 | 状態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :--- | +| [上級AI一：RAGとは何か、どのように動作するか](../../docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAGの原理と一般的なアーキテクチャの体系的な理解 | ✅ | +| [上級AI二：中・上級RAGとワークフローオーケストレーション：LangGraphを例に](../../docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | LangGraphを使用した複雑なワークフローと高度なRAGの設計 | 🚧 | + +
## 🛠️ 学習方法 -- 個人の能力に応じて、関連する章を選択的に読み实践し、問題があれば Issue で質問してください。 +- 自身のレベルに合わせて章を選択して学習し、実践してください。疑問点があればIssueで質問してください。 -## 💻 本课件をローカルで起動 +## 💻 ローカルでの起動方法 -### モダン手法 +### 現代的な方法 -AI IDE ダイアログボックス（vscode、cursor、trae など）で、以下のプロンプトを入力して本课件を起動： +AI IDEの対話ボックス（VS Code, Cursor, Traeなど）で以下のプロンプトを入力してください： ``` -このプロジェクトのローカルサービスを実行してください +このプロジェクトのローカルサービスを起動してください。 ``` -### 旧手法 +### 従来の方法 1. npm install 2. npm run dev -3. ブラウザを開いて `http://localhost:3000` にアクセスして確認。 +3. ブラウザで `http://localhost:3000` にアクセスしてください。 -## 🤝 貢献に参加 +## 🤝 貢献について -- もし問題を発見した場合、または本プロジェクトを改善できる点があると思われる場合は、Issue を提出してフィードバックしてください。提出後に誰も返信しない場合は、[保母チーム](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)のメンバーに連絡してフィードバックとフォローアップを受けることができます~ -- もしあなたが本プロジェクトへの貢献に参加したい場合は、Pull Request を提出してください。提出後に誰も返信しない場合は、[保母チーム](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)のメンバーに連絡してフィードバックとフォローアップを受けることができます~ -- もしあなたが Datawhale に非常に興味があり、新しいプロジェクトを開始したい場合は、[Datawhale オープンソースプロジェクトガイド](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)に従って操作してください~ +- 問題を見つけた場合や、改善案がある場合は、Issueでフィードバックをお願いします。 +- 貢献を希望される場合は、Pull Requestを送信してください。 +- 新しいプロジェクトの立ち上げに興味がある場合は、Datawhaleオープンソースプロジェクトガイドに従ってください。 -## 🙏 すべての貢献者に感謝 +## 🙏 貢献者への感謝 -- [散步-プロジェクト責任者](https://github.com/sanbuphy) (Datawhale メンバー) -- 方可-指導教官（Datawhale メンバー、清華大学） -- [Yerim Kang](https://github.com/yerim25)（实践项目部分-清華大学） -- 赵芷霖（実践プロジェクト部分-清華大学） -- [李亦萱](https://yixuan20.github.io/)（ページ美術デザイン-清華大学） -- AI Vibe Coding 101 ベータテストグループでアドバイスと体験を提供してくれたすべての仲間たち +- [散歩-プロジェクトリーダー](https://github.com/sanbuphy) (Datawhaleメンバー) +- 方可-アドバイザー (Datawhaleメンバー, 清華大学) +- [Yerim Kang](https://github.com/yerim25) (実践プロジェクト部分-清華大学) +- 趙芷霖 (実践プロジェクト部分-清華大学) +- [李亦萱](https://yixuan20.github.io/) (ページデザイン-清華大学) +- その他、suggestionをくださったすべてのベータテスターの皆様に感謝します。 ### 特別な感謝 -- [@Sm1les](https://github.com/Sm1les) さんの本プロジェクトへの支援と支持に感謝 -- 本プロジェクトに貢献してくれたすべての開発者に感謝 ❤️ +- [@Sm1les](https://github.com/Sm1les) 氏の多大なるサポートに感謝します。 +- プロジェクトに貢献してくださったすべての開発者、スターをくださった皆様に感謝します ❤️ + +
+ +

+ Stargazers +    + Forkers +

+ + + + + + + +
@@ -204,10 +385,10 @@ AI IDE ダイアログボックス（vscode、cursor、trae など）で、以 ## 📧 お問い合わせ
-

ご質問、ご提案、不満、または交流をご希望の場合は、以下の QR コードをスキャンしてください

- +

質問、提案、交流をご希望の方は、以下のQRコードをスキャンしてください

+ -

以下の QR コードをスキャンして公式アカウントをフォローしてください：Datawhale

+

公式アカウントをフォロー：Datawhale

@@ -216,7 +397,7 @@ AI IDE ダイアログボックス（vscode、cursor、trae など）で、以
クリエイティブ・コモンズ・ライセンス @@ -224,7 +405,7 @@ AI IDE ダイアログボックス（vscode、cursor、trae など）で、以
本作品は - クリエイティブ・コモンズ 表示 - 非営利 - 継承 4.0 国際ライセンス + クリエイティブ・コモンズ 表示 - 非営利 - 継承 4.0 国際 ライセンス の下でライセンスされています。
diff --git a/docs-readme/ko-KR/README.md b/docs-readme/ko-KR/README.md index 3d62f52..84b4ee2 100644 --- a/docs-readme/ko-KR/README.md +++ b/docs-readme/ko-KR/README.md @@ -4,23 +4,21 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _0부터, 프로젝트 기반 학습, 첫 번째 AI 제품 구축_ +# Easy-Vibe : 0에서 1까지 배우는 Vibe Coding

- 📌 온라인으로 읽기 시작하기 (Start Reading Online) + 📌 온라인 읽기 (Read Online) · ✨ 대화형 튜토리얼

- 온라인으로 읽기 · - 학습 맵 · - 커뮤니티 소통 + 온라인 읽기 · + 학습 지도 · + 커뮤니티 교류

@@ -39,161 +37,345 @@ 日本語 Español Français - 한국어 + Klingon + 한국어 العربية + Türkçe Tiếng_Việt Deutsch + বাংলা

- -## 🚀 프로젝트 소개 - -AI로 코드를 작성하려고 할 때 오류가 계속 발생하고, 포기하고 싶어지며, 프로그램을 실제로 온라인에 배포하는 방법을 명확히 알지 못할 때 😢 - -이 튜토리얼은 0에서 1까지 Vibe Coding 기술을 점진적으로 마스터할 수 있도록 특별히 설계되었습니다: - -- **1단계**: **미니게임부터 웹 프로토타입까지**, AI 프로그래밍 기초와 제품 사고 습득 -- **2단계**: **프론트엔드/백엔드 개발과 AI 능력**과 관련된 Vibe Coding 테크닉 학습, 완전한 애플리케이션 완성 -- **3단계**: **멀티플랫폼 복잡 애플리케이션** 구축 방법 마스터, 프로덕션급 애플리케이션으로 - -우리는 Vibe Coding을 마스터하고 체계적인 훈련을 결합하면, 한 사람이 프론트엔드 개발, 백엔드 개발, AI 능력 통합, 프로덕트 디자인을 모두 갖춘 개발자가 될 수 있다고 믿습니다. - -> **이 프로젝트는 주로 세 가지 유형의 학습자를 대상으로 합니다:** -> -> - **초보자(일반인 / 프로덕트 및 운용 담당자)**: 비기술 초보자가 핵심 개념을 이해하고 첫 번째 프로덕트 프로토타입을 완성하도록 지원 -> - **초중급 개발자(일정 기초가 있는 학생과 개발자)**: 프론트엔드/백엔드 Vibe Coding과 AI 능력 지식 습득 -> - **고급 개발자(기업/스타트업, 오픈소스/독립 개발자)**: 고급 개발 기술, 멀티플랫폼 개발 - -### 📖 콘텐츠 네비게이션 - + + + + + + + + + + + + + +
+ +
+ 초보자 전용 학습 지도 +
+ 기초 지식 제로를 위한 전용 안내, 명확한 경로 설계, "배우고 잊는" 악순환 탈출 + 		+ +
+ 친절한 이미지 튜토리얼 +
+ 상세한 이미지 설명, 마치 개인 과외 선생님이 옆에 있는 것처럼 따라 하기만 하면 습득 +
+ +
+ 몰입형 시뮬레이션 프로그래밍 +
+ 가상 마우스 자동 탐색으로 IDE 핵심 사용법을 빠르게 습득 + 		+ +
+ 눈으로 보는 AI 원리 +
+ 알고리즘 원리를 애니메이션화하여 AI가 이미지를 그리는 과정을 한눈에 이해 +
+ +
+ 게임처럼 배우는 RAG +
+ 독자적인 인터랙티브 컴포넌트로 클릭만 하면 RAG 데이터 흐름을 명확히 확인 + 		+ +
+ 시각화된 터미널 원리 +
+ 명령줄 조작을 시각화하여 백엔드 로직과 원리를 직관적으로 표시 +
- Learning Map +

⭐ 이곳을 클릭해 Star를 눌러 업데이트를 응원해주세요 ❤️

-### 총 부록 +AI 시대에 아이디어를 제품으로 만드는 사람은 기술이 가장 뛰어난 사람이 아니라 가장 먼저 행동에 옮기는 사람입니다. -[AI 능력 사전: 일반적인 AI 핵심 개념과 용어, 시나리오 설명](docs/zh-cn/appendix/ai-capability-dictionary.md) +AI 어시스턴트가 있어도 "코드를 모르겠다", "환경 설정을 못 하겠다"며 포기하는 분들이 많습니다. **Easy-Vibe는 이를 위해 태어났습니다.** 모든 사람이 기초 지식이 없다는 가정하에, 첫 줄의 코드를 작성하는 것부터 전후방 로직 이해, 그리고 최종 제품 배포까지 손을 잡고 안내해 드립니다. -### 1. 초보자 입문 및 제품 프로토타입 +- **대상**: 초보자, 제품 관리자(PM), 프론트엔드/백엔드/풀스택 개발자 +- **주제**: AI 프로그래밍, 풀스택 Web 애플리케이션 개발, AI Agent, 워크플로우 및 RAG 시스템 -| 장 | 주요 내용 | 상태 | -| :--------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | -| [서론: 학습 맵](docs/zh-cn/stage-0/0.1-learning-map/index.md) | 전체 학습 경로 가이드 | ✅ | -| [초급 1: AI 시대, 말할 수 있으면 프로그래밍 가능](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | 스네이크 게임 등 사례를 통해 AI 프로그래밍 능력을 처음 체험 | ✅ | -| [초급 2: AI IDE 도구 이해](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | IDE 사용법 배우기, 로컬에서 미니게임 제작 | ✅ | -| [초급 3: 직접 프로토타입 만들기](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | 요구사항 분석, AI 단일 페이지 생성, 다중 페이지 프로덕트 프로토타입 생성으로 | ✅ | -| [초급 4: 프로토타입에 AI 능력 추가](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | 일반적인 AI 능력(텍스트, 이미지, 비디오) 연결 방법 습득 | ✅ | -| [초급 5: 완전 프로젝트 실전](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 실제 시나리오 시뮬레이션, 사용자 피드백 수용 반복 개선, 프로젝트 완성 | ✅ | -| [대 과제: 완전한 웹 애플리케이션 프로토타입 만들기 및 전시](docs/zh-cn/stage-1/1.5-final-project/index.md) | 애플리케이션 완전 구현, 애플리케이션 효과 전시 | ✅ | +--- + +Easy-Vibe는 다음 단계들을 통해 당신을 0에서 1로 안내합니다: + +| 단계 | 핵심 기술 | 산출물 | +| ------------ | -------------------------------- | ----------------------------------------- | +| **1단계** | AI 프로그래밍 입문, 제품 사고, 프로토타입 설계 | 대화형 미니 게임, Web 앱 프로토타입 (초보자 & PM) | +| **2단계** | 풀스택 개발, AI 통합, 데이터베이스 | 완전한 풀스택 AI 애플리케이션 | +| **3단계** | Claude Code 심화, 미니 프로그램 및 안드로이드 개발 | 프로덕션급 멀티 플랫폼 애플리케이션 | +| **부록** | 컴퓨터 및 AI 기초 개념 이해 지원 | 9대 지식 영역, 80개 이상의 대화형 주제 | + +## 🔥 News + +- **[2026-02-25]** [부록 지식 창고](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) 업데이트. 9대 지식 영역, 80개 이상의 대화형 주제 포함. +- **[2026-01-27]** 안드로이드 및 iOS 플랫폼 앱 개발 튜토리얼 추가. +- **[2026-01-19]** Prompt Engineering, AI 진화사, 인증 설계, Git 원리 등 일련의 대화형 데모 컴포넌트 출시. + +
+Past News + +- **[2026-01-16]** 프로젝트 구조 재구성, "초보자 입문" 장을 공식적으로 설정하여 진입 장벽 완화. +- **[2026-01-14]** 1단계 "제품 프로토타입 구축" 문서 대규모 업데이트 완료. +- **[2026-01-13]** 문서 아키텍처 재구축 완료, 다국어(i18n) 전면 지원. +- **[2026-01-01]** 프로젝트 핵심 학습 지도 (Learning Map) 출시, 학습 경로 명확화. +
+ +### 📖 콘텐츠 탐색 + +
+ Learning Map +
+ +### 📚 부록 지식 창고 + +> **9대 지식 영역**, **80개 이상의 대화형 주제**를 통해 컴퓨터 하부 구조부터 AI 최전선까지의 핵심 개념을 애니메이션과 시각화 컴포넌트로 직관적으로 이해할 수 있도록 돕습니다. +> +> 👉 [전체 부록 보기](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) · [AI 능력 사전](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary) + + + + + + + + + + + + + + + + + +
+ 💻 컴퓨터 기초

+ • 트랜지스터에서 CPU까지
+ • 운영체제
+ • 데이터 인코딩, 저장 및 전송
+ • 네트워크: 두 컴퓨터의 대화법
+ • 자료구조
+ • 알고리즘 사고 입문 + 		+ 🔧 개발 도구

+ • Git: 코드 타임머신
+ • 명령줄 및 Shell 스크립트
+ • 패키지 매니저
+ • 디버깅의 예술
+ • 정규표현식
+ • 환경 변수와 PATH + 		+ 🌐 브라우저 및 프론트엔드

+ • JavaScript 언어 심화
+ • 브라우저 렌더링 파이프라인
+ • 프론트엔드 프레임워크 비교
+ • 그래픽 및 애니메이션
+ • 웹 성능 측정 및 최적화
+ • 프론트엔드 엔지니어링 전체상 +
+ 🖥️ 서버 및 백엔드

+ • HTTP 프로토콜
+ • API 설계 철학
+ • 인증 및 인가 체계
+ • 병행성, 비동기 및 멀티스레딩
+ • 메시지 큐 및 이벤트 드리븐
+ • 백엔드 계층 구조 + 		+ 📊 데이터

+ • SQL
+ • 데이터베이스 원리
+ • 데이터 트래킹 및 사용자 행동 수집
+ • 데이터 분석 기초
+ • A/B 테스트 및 실험 기반
+ • 데이터 시각화 및 대시보드 + 		+ 🏗️ 아키텍처 및 시스템 설계

+ • 모놀리스에서 마이크로서비스로의 진화
+ • 분산 시스템의 도전 과제
+ • 고가용성 및 재해 복구
+ • 시스템 설계 방법론 +
+ ☁️ 인프라 및 운영

+ • Docker 컨테이너화
+ • Kubernetes 오케스트레이션
+ • CI / CD 자동화
+ • 도메인, DNS 및 HTTPS
+ • 모니터링, 로그 및 알람
+ • 코드형 인프라 (IaC) + 		+ 🤖 인공지능

+ • 거대 언어 모델의 작동 원리
+ • Transformer와 어텐션 메커니즘
+ • RAG 아키텍처
+ • AI Agent와 도구 호출
+ • 프롬프트 엔지니어링
+ • 이미지 생성 원리 + 		+ 🎯 엔지니어적 소양

+ • 코드 품질 및 리팩토링
+ • 테스트 전략
+ • 디자인 패턴
+ • 보안 사고 및 공방 기초
+ • 기술 문서 작성
+ • 오픈소스 협업 +
+ +### 1단계: 제로 베이스 입문 + +| 장 | 핵심 내용 | 상태 | +| :----------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | +| [머리말: 학습 지도](../../docs/zh-cn/stage-0/0.1-learning-map/index.md) | 전체 학습 경로 안내 | ✅ | +| [초급 1: AI 시대, 말이 곧 프로그래밍](../../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | 스네이크 게임 사례를 통해 AI 프로그래밍 경험 | ✅ | +| [초급 2: 좋은 아이디어 찾기](../../docs/zh-cn/stage-1/1.0-finding-great-idea/index.md) | 제품 아이디어 탐색 및 검증 방법 습득 | ✅ | +| [초급 3: AI IDE 도구 이해하기](../../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | IDE 사용법 습득, 로컬에서 미니 게임 제작 | ✅ | +| [초급 4: 프로토타입 직접 만들기](../../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | 요구사항 분석부터 AI 기반 프로토타입 생성까지 | ✅ | +| [초급 5: 프로토타입에 AI 능력 더하기](../../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | AI 모델(텍스트, 이미지, 비디오) 연동 방법 습득 | ✅ | +| [초급 6: 전체 프로젝트 실전](../../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 실제 시나리오 시뮬레이션 및 피드백 기반 개선 | ✅ | #### 부록: 비즈니스 사고 -| 장 | 주요 내용 | 상태 | -| :---------------------------------------------------------------------------------------------------- | :-------------------------------------------------- | :--- | -| [부록 A: 프로덕트 사고 및 솔루션 설계](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | 0에서 1까지 프로덕트 만들 때 필요한 사고 프레임워크 | ✅ | -| [부록 B: AI 산업 적용 시나리오 참조 (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | 다양한 산업에서 AI 적용 사례 이해 | ✅ | -| [부록 C: AI 소비 시나리오 영감 참조 (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | 소비자 제품에서 AI 적용 사례 탐색 | ✅ | +| 장 | 핵심 내용 | 상태 | +| :----------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [부록 A: 제품 사고와 방안 설계](../../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | 제품 제작 시 고려해야 할 사고 프레임워크 | ✅ | +| [부록 B: AI 산업별 적용 사례 (B2B)](../../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | 산업별 AI 활용 시나리오 이해 | ✅ | +| [부록 C: AI 소비 시나리오 영감 (B2C)](../../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | 소비재 제품에서의 AI 활용 시나리오 탐색 | ✅ | -#### 부록: 기술 솔루션 +#### 부록: 기술 방안 -| 장 | 주요 내용 | 상태 | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | :--- | -| [부록 D: 코드 작성 시 오류 발생 시 대처 방법](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Vibe Coding의 일반적인 오류 및 문제 해결 방법 | ✅ | -| [부록 E: 7가지 AI 프로그래밍 도구 비교](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 주요 AI 프로그래밍 플랫폼 비교 테스트 | ✅ | -| [부록 F: 디자인 및 프로그래밍 에이전트로 웹사이트 설계](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | AI 에이전트 협업 사용 방법 학습 | ✅ | +| 장 | 핵심 내용 | 상태 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [부록 D: 코드 오류 발생 시 대처법](../../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Vibe coding 시 자주 발생하는 오류 및 해결법 | ✅ | +| [부록 E: 7가지 AI 프로그래밍 도구 비교](../../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 주요 AI 프로그래밍 플랫폼 비교 테스트 | ✅ | +| [부록 F: Agent를 활용한 웹사이트 설계](../../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | AI 에이전트 협업 방법 습득 | ✅ | -### 2. 초중급 개발 엔지니어 +
+2단계: 중급 개발자 -#### 프론트엔드 부분 +#### 프론트엔드 -| 장 | 주요 내용 | 상태 | -| :---------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- | :--- | -| [프론트엔드 0: lovart 사용하여 소재 생성](docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | lovart를 사용하여 캐릭터, 장면 등 시각 자료 일괄 생성, UI 디자인과 프론트엔드 개발에 자료 기반 제공 | 🚧 | -| [프론트엔드 1: Figma와 MasterGo 입문](docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | 디자인 도구로 정보 아키텍처와 페이지 구조 정리, 프론트엔드 구현 기반 마련 | 🚧 | -| [프론트엔드 2: 첫 번째 현대 애플리케이션 구축 - UI 디자인](docs/zh-cn/stage-2/frontend/2.2-ui-design/) | 디자인 안을 기반으로 컴포넌트화 인터페이스 완성, 디자인에서 코드까지의 첫 번째 경로 실현 | 🚧 | -| [프론트엔드 3: UI 디자인 사양 및 다중 프로덕트 UI 디자인 참조](docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 통합된 메인 비주얼을 중심으로 다중 프로덕트 인터페이스 확장, 체계적 디자인 능력 연습 | 🚧 | -| [프론트엔드 4: 함께 해리포트 초상화 만들기](docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | 0에서 1까지 AI 능력을 통합한 프론트엔드 애플리케이션 제작, 디자인과 개발 연결 | ✅ | +| 장 | 핵심 내용 | 상태 | +| :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | +| [프론트엔드 0: Lovart로 에셋 생성](../../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | 시각적 에셋(캐릭터, 배경 등) 대량 생성 방법 | 🚧 | +| [프론트엔드 1: Figma & MasterGo 입문](../../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | 설계 도구로 정보 구조 및 페이지 구성 정리 | 🚧 | +| [프론트엔드 2: 첫 현대적 앱 구축 - UI 설계](../../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | 디자인에서 코드로 이어지는 컴포넌트 기반 UI 구현 | 🚧 | +| [프론트엔드 3: UI 설계 표준 및 프로젝트 설계](../../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 통일된 비주얼 기반의 시스템 설계 연습 | 🚧 | +| [프론트엔드 4: 호그와트 초상화 만들기](../../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | AI 기능이 포함된 프론트엔드 앱 직접 제작 | ✅ | -#### 백엔드와 풀스택 부분 +#### 백엔드 및 풀스택 -| 장 | 주요 내용 | 상태 | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- | -| [백엔드 1: API란](docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTP 인터페이스와 요청-응답 모델 이해, 백엔드 통합과 연동 조정 준비 | ✅ | -| [백엔드 2: 데이터베이스에서 Supabase로](docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Supabase상에서 데이터베이스와 API 구현, 데이터 모델과 프론트엔드 페이지 연결 | ✅ | -| [백엔드 3: 대규모 언어 모델 지원 인터페이스 코드 및 문서 작성](docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | 대규모 언어 모델을 활용하여 인터페이스와 데이터베이스 문서 및 코드 생성 지원, 읽기 쉽고 테스트 가능한 백엔드 실현 | 🚧 | -| [백엔드 4: Git 워크플로우](docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | Git 워크플로우에서 코드 관리, 버전 관리 및 협업 수행 | ✅ | -| [백엔드 5: Zeabur 배포](docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | 애플리케이션을 Zeabur에 배포하여 온라인화 | ✅ | -| [백엔드 6: 현대 CLI 개발 도구](docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | CLI 계열 AI 프로그래밍 도구 사용하여 개발과 디버깅 가속화, 개인 엔지니어링 워크플로우 형성 | ✅ | -| [백엔드 7: Stripe 등 유료 시스템 통합 방법](docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 결제 시스템 연결, 유료 경로와 기본 정산 흐름 완성 | 🚧 | -| [대 과제 1: 첫 번째 현대 애플리케이션 구축 - 풀스택 앱](docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | 프론트엔드, 백엔드, 결제 모듈 통합, 온라인 가능한 풀스택 웹 애플리케이션 완성 | 🚧 | -| [대 과제 2: 현대 프론트엔드 컴포넌트 라이브러리 + Trae 실전](docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | 현대 프론트엔드 컴포넌트 라이브러리와 Trae 사용, 로그인/등록 가능하고 유료 지원 프로덕트 독립 완성 | 🚧 | +| 장 | 핵심 내용 | 상태 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | +| [백엔드 1: API란 무엇인가](../../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | HTTP 인터페이스 및 요청-응답 모델 이해 | ✅ | +| [백엔드 2: DB에서 Supabase까지](../../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | Supabase 기반 DB 및 API 구축 | ✅ | +| [백엔드 3: AI 기반 API 코드 및 문서 생성](../../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | AI를 활용한 효율적인 백엔드 코드 생성 | 🚧 | +| [백엔드 4: Git 워크플로우](../../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | 버전 관리 및 협업을 위한 Git 활용법 | ✅ | +| [백엔드 5: Zeabur 배포](../../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | 애플리케이션 실제 배포 및 운영 | ✅ | +| [백엔드 6: 현대적 CLI 개발 도구](../../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | CLI 기반 AI 도구로 개발 속도 향상 | ✅ | +| [백엔드 7: 결제 시스템 연동 (Stripe)](../../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 결제 및 정산 프로세스 구축 | 🚧 | +| [프로젝트 1: 첫 현대적 풀스택 앱 구축](../../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | 전 과정을 통합한 실제 웹 서비스 제작 | 🚧 | +| [프로젝트 2: UI 라이브러리 + Trae 실전](../../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | 독립적인 상용 수준 제품 제작 연습 | 🚧 | #### AI 능력 부록 -| 장 | 주요 내용 | 상태 | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :--- | -| [AI 1: Dify 입문과 지식 베이스 통합](docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify Workflow와 기본 RAG 사용하여 도구 계열 프로덕트 구축, 이후 애플리케이션 업그레이드 모델 사례 작성 | ✅ | -| [AI 2: AI 사전 검색 및 멀티모달 API 통합 학습](docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 적절한 모델과 API 검색 방법 학습, 텍스트, 이미지 등 멀티모달 능력을 프로덕트에 통합 | 🚧 | +| 장 | 핵심 내용 | 상태 | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- | +| [AI 1: Dify 입문 및 지식 창고 연동](../../docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify Workflow 및 RAG 기반 툴 제작 | ✅ | +| [AI 2: AI 사전 검색 및 멀티모달 API 연동](../../docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 적합한 모델 탐색 및 멀티모달 능력 연동 | 🚧 | -### 3. 고급 개발 엔지니어 +
-| 장 | 주요 내용 | 상태 | -| :--------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :--- | -| [고급 1: MCP와 Claude Code Skills](docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | MCP와 Skills를 통해 IDE 능력 확장, 외부 서비스를 도구로 연결 | 🚧 | -| [고급 2: Coding Tools를 장시간 작동시키는 방법](docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 장시간 실행되는 작업 설계 및 구성, Coding Tools를 더 안정적이고 신뢰할 수 있게 | 🚧 | -| [고급 3: 멀티플랫폼 개발: 위챗 미니 프로그램 구축 방법](docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | 위챗 미니 프로그램 생태계 이해, 공식 템플릿부터 출시까지 프론트엔드 미니 프로그램 완성 | ✅ | -| [고급 4: 멀티플랫폼 개발: 위챗 미니 프로그램 구축 방법 - 백엔드 포함](docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | 미니 프로그램에 데이터베이스와 백엔드 로직 통합, 완전한 비즈니스 폐루프 실현 | 🚧 | -| [고급 5: 멀티플랫폼 개발: 안드로이드 앱 구축 방법](docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Expo 등 도구 사용, Web/네이티브 일체화 안드로이드 앱 개발 완성 | 🚧 | -| [고급 6: 멀티플랫폼 개발: iOS 앱 구축 방법](docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Expo 등 도구 사용, Web/네이티브 일체화 iOS 앱 개발 완성 | 🚧 | -| [고급 7: 자신만의 개인 웹페이지와 학술 블로그 구축 방법](docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 선정, 구축부터 배포까지, 개인 프로젝트와 학술 성과를 전시하는 장기 온라인 홈페이지 구축 | 🚧 | +
+3단계: 고급 개발자 + +| 장 | 핵심 내용 | 상태 | +| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | +| [고급 1: MCP 및 Claude Code Skills](../../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | IDE 능력 확장 및 도구 연동 | 🚧 | +| [고급 2: Coding Tools 장기 작업 환경 구축](../../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 안정적인 장기 작업 태스크 설계 | 🚧 | +| [고급 3: 위챗 미니 프로그램 개발](../../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | 미니 프로그램 생태계 및 배포 이해 | ✅ | +| [고급 4: 미니 프로그램 백엔드 연동](../../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | 복잡한 비즈니스 로직 연동 | 🚧 | +| [고급 5: 안드로이드 앱 개발](../../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | Expo 기반 네이티브 앱 개발 | ✅ | +| [고급 6: iOS 앱 개발](../../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | Expo 기반 iOS 앱 개발 | ✅ | +| [고급 7: 개인 웹사이트 및 학술 블로그 구축](../../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 개인 브랜드 구축을 위한 블로그 제작 | 🚧 | #### AI 능력 부록 -| 장 | 주요 내용 | 상태 | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :--- | -| [고급 AI 1: RAG란 무엇이며 어떻게 작동하는가](docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 원리와 일반적인 아키텍처 체계적 이해, 복잡한 애플리케이션에 지식 검색 기반 제공 | ✅ | -| [고급 AI 2: 중고급 RAG와 워크플로우 편성: LangGraph 예시](docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | LangGraph 등 도구 사용하여 다단계 워크플로우와 중고급 RAG 시스템 설계 | 🚧 | +| 장 | 핵심 내용 | 상태 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :--- | +| [고급 AI 1: RAG의 이해와 작동 원리](../../docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 아키텍처 및 원리 심화 이해 | ✅ | +| [고급 AI 2: LangGraph 기반 AI 워크플로우](../../docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | 복잡한 AI 워크플로우 설계 | 🚧 | + +
## 🛠️ 학습 방법 -- 개인 능력에 따라 관련 장을 선택적으로 읽고 실습하며, 문제가 있으면 Issue로 질문해 주세요. +- 개인의 능력치에 맞는 장을 선택하여 실습하세요. 문의 사항은 Issue를 이용해주세요. -## 💻 이 과정을 로컬에서 시작 +## 💻 로컬에서 실행하기 -### 현대적 방법 +### 최신 방법 -AI IDE 대화상자(vscode, cursor, trae 등)에서 다음 프롬프트를 입력하여 이 과정을 시작: +AI IDE(VS Code, Cursor, Trae 등) 대화창에 다음 명령을 입력하세요: ``` -이 프로젝트의 로컬 서비스를 실행해주세요 +이 프로젝트의 로컬 서비스를 실행해 줘. ``` -### 구식 방법 +### 기존 방법 1. npm install 2. npm run dev -3. 브라우저를 열고 `http://localhost:3000`에 접속하여 확인. +3. 브라우저에서 `http://localhost:3000`에 접속하여 확인하세요. -## 🤝 기여 참여 +## 🤝 기여하기 -- 문제를 발견했거나 이 프로젝트를 개선할 수 있는 점이 있다고 생각되시면 Issue를 제출하여 피드백해 주세요. 제출 후 아무도 응답하지 않으면 [보모 팀](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) 멤버에게 연락하여 피드백과 후속 조치를 받을 수 있습니다~ -- 이 프로젝트에 기여하고 싶으시면 Pull Request를 제출해 주세요. 제출 후 아무도 응답하지 않으면 [보모 팀](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) 멤버에게 연락하여 피드백과 후속 조치를 받을 수 있습니다~ -- Datawhale에 매우 흥미가 있고 새 프로젝트를 시작하고 싶으시면 [Datawhale 오픈소스 프로젝트 가이드](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)에 따라 조작해 주세요~ +- 문제점 발견이나 개선 사항 제안은 Issue를 통해 해주세요. +- 프로젝트 기여를 원하시면 Pull Request를 보내주세요. +- Datawhale의 새로운 프로젝트 발의는 오픈소스 가이드를 참조하세요. -## 🙏 모든 기여자에게 감사 +## 🙏 도움 주신 분들 -- [散步-프로젝트 책임자](https://github.com/sanbuphy) (Datawhale 회원) -- 방可-지도 교사(Datawhale 회원, 칭화대학) -- [Yerim Kang](https://github.com/yerim25)（실습 프로젝트 부분-칭화대학） -- 赵芷霖（실습 프로젝트 부분-칭화대학） -- [李亦萱](https://yixuan20.github.io/)（페이지 미술 디자인-칭화대학） -- AI Vibe Coding 101 베타 테스트 그룹에서 제안과 경험을 제공한 모든 동료들 +- [산부(散步) - 프로젝트 리더](https://github.com/sanbuphy) (Datawhale 멤버) +- 팡커(方可) - 지도 교수 (Datawhale 멤버, 칭화대) +- [Yerim Kang](https://github.com/yerim25) (칭화대) +- 자오즈린(趙芷霖) (칭화대) +- [리이쉬안(李亦萱)](https://yixuan20.github.io/) (디자인, 칭화대) +- 리우스이(劉思怡) (칭화대) +- suggestion을 주신 모든 베타 테스터 분들께 감사드립니다. -### 특별한 감사 +### 특별 감사 -- [@Sm1les](https://github.com/Sm1les) 님이 이 프로젝트에 대한 도움과 지원에 감사 -- 이 프로젝트에 기여한 모든 개발자에게 감사 ❤️ +- [@Sm1les](https://github.com/Sm1les) 님의 도움과 지원에 감사드립니다. +- 기여해주신 모든 개발자분들과 Star를 눌러주신 분들께 감사드립니다 ❤️ + +
+ +

+ Stargazers +    + Forkers +

+ + + + + + + +
@@ -201,13 +383,13 @@ AI IDE 대화상자(vscode, cursor, trae 등)에서 다음 프롬프트를 입
-## 📧 문의하기 +## 📧 연락처
-

질문, 제안, 불만, 또는 소통을 원하시면 아래 QR 코드를 스캔해 주세요

- +

질문이나 제안, 교류를 원하시면 아래 QR 코드를 스캔해 주세요.

+ -

아래 QR 코드를 스캔하여 공식 계정을 팔로우해 주세요: Datawhale

+

Datawhale 공식 계정 팔로우:

@@ -216,17 +398,17 @@ AI IDE 대화상자(vscode, cursor, trae 등)에서 다음 프롬프트를 입
크리에이티브 커먼즈 라이선스
-이 저작물은 +본 저작물은 크리에이티브 커먼즈 저작자표시-비영리-동일조건변경허락 4.0 국제 라이선스 -에 따라 사용이 허가되었습니다. +에 따라 이용할 수 있습니다.
## Star History diff --git a/docs-readme/vi-VN/README.md b/docs-readme/vi-VN/README.md index 256bde4..976e97a 100644 --- a/docs-readme/vi-VN/README.md +++ b/docs-readme/vi-VN/README.md @@ -4,22 +4,20 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _Từ số không, học tập dựa trên dự án, xây dựng sản phẩm AI đầu tiên của bạn_ +# Easy-Vibe : Học Vibe Coding từ 0 đến 1

- 📌 Bắt đầu đọc online (Start Reading Online) + 📌 Đọc trực tuyến (Read Online) · ✨ Hướng dẫn tương tác

- Đọc online · - Bản đồ học tập · + Đọc trực tuyến · + Bản đồ học tập · Cộng đồng

@@ -39,195 +37,49 @@ 日本語 Español Français + Klingon 한국어 العربية - Tiếng_Việt + Türkçe + Tiếng_Việt Deutsch + বাংলা

+ + + + + +
+ +
+ Bản đồ học tập độc quyền cho người mới bắt đầu +
+ Hướng dẫn từ con số 0, lộ trình rõ ràng, tạm biệt việc "học trước quên sau" + 		+ +
+ Hướng dẫn hình ảnh từng bước +
+ Giải thích chi tiết bằng hình ảnh, như có gia sư riêng bên cạnh +
-## 🚀 Giới thiệu dự án +Trong thời đại AI, những người biến ý tưởng thành sản phẩm thường không phải là những người có kỹ thuật mạnh nhất, mà là những người có hành động đầu tiên. **Easy-Vibe ra đời vì điều này.** Chúng tôi sẽ cầm tay chỉ việc cho bạn, từ việc viết dòng code đầu tiên đến việc hiểu logic front-end và back-end, và cuối cùng là đưa sản phẩm của bạn lên mạng. -Khi bạn cố gắng viết code bằng AI, liên tục gặp lỗi, thường muốn từ bỏ và không rõ cách đưa chương trình của bạn lên thực tế 😢 +- **Đối tượng**: Người mới bắt đầu, Quản lý sản phẩm (PM), Lập trình viên Front-end / Back-end / Full-stack +- **Chủ đề**: Lập trình AI, Phát triển ứng dụng Web Full-stack, AI Agent, Workflow và hệ thống RAG -Hướng dẫn này được thiết kế đặc biệt để đưa bạn từ 0 đến 1, làm chủ dần các kỹ thuật Vibe Coding: +--- -- **Giai đoạn 1**: **Từ mini-game đến nguyên mẫu web**, nắm vững cơ sở lập trình AI và tư duy sản phẩm -- **Giai đoạn 2**: Học **phát triển frontend/backend và khả năng AI** liên quan đến kỹ thuật Vibe Coding, hoàn thành ứng dụng hoàn chỉnh -- **Giai đoạn 3**: Làm chủ xây dựng **ứng dụng phức tạp đa nền tảng**, hướng tới ứng dụng cấp sản xuất +Easy-Vibe dẫn dắt bạn từ 0 đến 1 qua ba giai đoạn: -Chúng tôi tin rằng thông qua việc làm chủ Vibe Coding kết hợp với đào tạo có hệ thống, một người có thể trở thành nhà phát triển kết hợp phát triển frontend, phát triển backend, tích hợp khả năng AI và thiết kế sản phẩm. +| Giai đoạn | Kỹ năng cốt lõi | Sản phẩm đầu ra | +| ------------ | -------------------------------- | ----------------------------------------- | +| **Giai đoạn 1** | Nhập môn lập trình AI, Tư duy sản phẩm, Thiết kế Prototype | Trò chơi nhỏ tương tác, Prototype Web (Người mới & PM) | +| **Giai đoạn 2** | Phát triển Full-stack, Tích hợp AI, Cơ sở dữ liệu | Ứng dụng AI Full-stack hoàn chỉnh | +| **Giai đoạn 3** | Kỹ thuật Claude Code nâng cao, Mobile & Mini-app | Ứng dụng đa nền tảng cấp sản xuất | +| **Phụ lục** | Hiểu các khái niệm cơ bản về Máy tính & AI | 9 lĩnh vực kiến thức, hơn 80 chuyên đề tương tác | -> **Dự án này chủ yếu hướng tới ba loại người học:** -> -> - **Người mới bắt đầu (người bình thường / sản phẩm và vận hành)**: Giúp người học phi kỹ thuật hiểu các khái niệm chính và hoàn thành nguyên mẫu sản phẩm đầu tiên -> - **Nhà phát triển cấp sơ-trung (sinh viên và nhà phát triển có cơ sở nhất định)**: Làm chủ kiến thức Vibe Coding frontend/backend và khả năng AI -> - **Nhà phát triển cấp cao (công ty và startup, mã nguồn mở và nhà phát triển độc lập)**: Kỹ thuật phát triển cấp cao, phát triển đa nền tảng - -### 📖 Điều hướng nội dung - -
- Learning Map -
- -### Phụ lục tổng quát - -[Từ điển khả năng AI: các khái niệm cốt lõi AI phổ biến, thuật ngữ và giải thích kịch bản](docs/appendix/ai-capability-dictionary.md) - -### 1. Nhập môn cho người mới và Nguyên mẫu sản phẩm - -| Chương | Nội dung chính | Trạng thái | -| :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------- | :--------- | -| [Lời nói đầu: Bản đồ học tập](docs/zh-cn/stage-0/0.1-learning-map/index.md) | Hướng dẫn lộ trình học tập tổng thể | ✅ | -| [Sơ cấp 1: Kỷ nguyên AI, biết nói là biết lập trình](docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | Trải nghiệm khả năng lập trình AI lần đầu qua các trường hợp như Snake | ✅ | -| [Sơ cấp 2: Biết các công cụ IDE AI](docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | Học sử dụng IDE, tạo mini-game cục bộ | ✅ | -| [Sơ cấp 3: Tự làm nguyên mẫu](docs/zh-cn/stage-1/1.2-building-prototype/index.md) | Phân tích yêu cầu, tạo trang đơn bằng AI, đến tạo nguyên mẫu sản phẩm đa trang | ✅ | -| [Sơ cấp 4: Thêm khả năng AI vào nguyên mẫu](docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | Học kết nối các khả năng AI phổ biến (văn bản, hình ảnh, video) | ✅ | -| [Sơ cấp 5: Dự án hoàn chỉnh thực chiến](docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | Mô phỏng kịch bản thực tế, chấp nhận phản hồi người dùng để cải tiến, hoàn thành dự án | ✅ | -| [Đề tài lớn: Tạo nguyên mẫu ứng dụng web hoàn chỉnh và trưng bày](docs/zh-cn/stage-1/1.5-final-project/index.md) | Thực hiện ứng dụng hoàn chỉnh, trình bày hiệu ứng ứng dụng | ✅ | - -#### Phụ lục: Tư duy Kinh doanh - -| Chương | Nội dung chính | Trạng thái | -| :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--------- | -| [Phụ lục A: Tư duy Sản phẩm và Thiết kế Giải pháp](docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | Các khung tư duy cần thiết để tạo sản phẩm từ số không đến một | ✅ | -| [Phụ lục B: Tham khảo Ứng dụng AI trong Ngành (B2B)](docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | Hiểu các ứng dụng AI trong các ngành khác nhau | ✅ | -| [Phụ lục C: Tham khảo Cảm hứng Kịch bản Tiêu dùng AI (B2C)](docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | Khám phá các ứng dụng AI trong sản phẩm tiêu dùng | ✅ | - -#### Phụ lục: Giải pháp Kỹ thuật - -| Chương | Nội dung chính | Trạng thái | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- | :--------- | -| [Phụ lục D: Làm gì khi Gặp lỗi khi Viết Code](docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | Các lỗi phổ biến trong Vibe Coding và phương pháp khắc phục | ✅ | -| [Phụ lục E: So sánh 7 Công cụ Lập trình AI](docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | So sánh và thử nghiệm các nền tảng lập trình AI chính | ✅ | -| [Phụ lục F: Thiết kế Website với Agent Thiết kế và Lập trình](docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | Học cách sử dụng AI Agent cộng tác | ✅ | - -### 2. Kỹ sư phát triển cấp sơ-trung - -#### Phần Frontend - -| Chương | Nội dung chính | Trạng thái | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :--------- | -| [Frontend 0: Sử dụng lovart tạo tài sản](docs/stage-2/frontend/2.0-lovart-assets/) | Sử dụng lovart tạo hàng loạt tài sản hình ảnh như nhân vật, cảnh, cung cấp cơ sở tài sản cho thiết kế UI và phát triển frontend | 🚧 | -| [Frontend 1: Nhập môn Figma và MasterGo](docs/stage-2/frontend/2.1-figma-mastergo/) | Sử dụng công cụ thiết kế tổ chức kiến trúc thông tin và cấu trúc trang, chuẩn bị cơ sở cho triển khai frontend | 🚧 | -| [Frontend 2: Xây dựng ứng dụng hiện đại đầu tiên - Thiết kế UI](docs/stage-2/frontend/2.2-ui-design/) : Hoàn thành giao diện dựa trên thành phần từ thiết kế, thực hiện lộ trình đầu tiên từ thiết kế đến code | 🚧 | -| [Frontend 3: Tham khảo thông số thiết kế UI và thiết kế UI đa sản phẩm](docs/stage-2/frontend/2.3-multi-product-ui/) : Mở rộng giao diện đa sản phẩm quanh một hình ảnh chính thống nhất, thực hành khả năng thiết kế có hệ thống | 🚧 | -| [Frontend 4: Cùng làm chân dung Hogwarts](docs/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) : Tạo ứng dụng frontend có khả năng AI tích hợp từ 0 đến 1, kết nối thiết kế và phát triển | ✅ | - -#### Phần Backend và Full Stack - -| Chương | Nội dung chính | Trạng thái | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | :--------- | -| [Backend 1: API là gì](docs/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) : Hiểu giao diện HTTP và mô hình yêu cầu-phản hồi, chuẩn bị tích hợp backend và phối hợp | ✅ | -| [Backend 2: Từ cơ sở dữ liệu đến Supabase](docs/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) : Triển khai cơ sở dữ liệu và API trên Supabase, kết nối mô hình dữ liệu với trang frontend | ✅ | -| [Backend 3: LLM hỗ trợ viết code giao diện và tài liệu](docs/stage-2/backend/2.3-ai-interface-code/) : Sử dụng LLM hỗ trợ tạo tài liệu và code cho giao diện và cơ sở dữ liệu, thực hiện backend có thể đọc và kiểm tra | 🚧 | -| [Backend 4: Quy trình làm việc Git](docs/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) : Quản lý code trong quy trình làm việc Git, thực hiện kiểm soát phiên bản và cộng tác | ✅ | -| [Backend 5: Triển khai Zeabur](docs/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) : Triển khai ứng dụng lên Zeabur để đưa vào hoạt động | ✅ | -| [Backend 6: Công cụ phát triển CLI hiện đại](docs/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) : Sử dụng công cụ lập trình AI loại CLI để tăng tốc phát triển và gỡ lỗi, hình thành quy trình kỹ thuật cá nhân | ✅ | -| [Backend 7: Cách tích hợp hệ thống thanh toán như Stripe](docs/stage-2/backend/2.7-stripe-payment/) : Kết nối hệ thống thanh toán, hoàn thành quy trình thanh toán và quy trình thanh toán cơ bản | 🚧 | -| [Đề tài lớn 1: Xây dựng ứng dụng hiện đại đầu tiên - Ứng dụng full stack](docs/stage-2/assignments/2.1-fullstack-app/) : Tích hợp frontend, backend và module thanh toán, hoàn thành ứng dụng web full stack sẵn sàng sản xuất | 🚧 | -| [Đề tài lớn 2: Thư viện thành phần frontend hiện đại + Trae thực chiến](docs/stage-2/assignments/2.2-modern-frontend-trae/) : Sử dụng thư viện thành phần frontend hiện đại và Trae, hoàn thành độc lập một sản phẩm có đăng nhập/đăng ký và hỗ trợ thanh toán | 🚧 | - -#### Phụ lục khả năng AI - -| Chương | Nội dung chính | Trạng thái | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | :--------- | -| [AI 1: Nhập môn Dify và tích hợp cơ sở kiến thức](docs/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) : Sử dụng Dify Workflow và RAG cơ bản để xây dựng sản phẩm loại công cụ, tạo ví dụ cho nâng cấp ứng dụng trong tương lai | ✅ | -| [AI 2: Học tra cứu từ điển AI và tích hợp API đa phương thức](docs/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) : Học tìm kiếm mô hình và API phù hợp, tích hợp khả năng đa phương thức như văn bản, hình ảnh vào sản phẩm | 🚧 | - -### 3. Kỹ sư phát triển cấp cao - -| Chương | Nội dung chính | Trạng thái | -| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | :--------- | -| [Cao cấp 1: MCP và Claude Code Skills](docs/stage-3/core-skills/3.1-mcp-claude-code-skills/) : Mở rộng khả năng IDE qua MCP và Skills, kết nối dịch vụ bên ngoài như công cụ | 🚧 | -| [Cao cấp 2: Cách để Coding Tools hoạt động lâu](docs/stage-3/core-skills/3.2-long-running-tasks/) : Thiết kế và cấu hình nhiệm vụ chạy dài, làm Coding Tools ổn định và đáng tin cậy hơn | 🚧 | -| [Cao cấp 3: Phát triển đa nền tảng: Cách xây dựng chương trình nhỏ WeChat](docs/stage-3/cross-platform/3.3-wechat-miniprogram/) : Hiểu hệ sinh thái chương trình nhỏ WeChat, hoàn thành chương trình nhỏ frontend từ mẫu chính thức đến phát hành | ✅ | -| [Cao cấp 4: Phát triển đa nền tảng: Cách xây dựng chương trình nhỏ WeChat - Bao gồm backend](docs/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) : Tích hợp cơ sở dữ liệu và logic backend vào chương trình nhỏ, thực hiện vòng tuần hoàn hoạt động hoàn chỉnh | 🚧 | -| [Cao cấp 5: Phát triển đa nền tảng: Cách xây dựng ứng dụng Android](docs/stage-3/cross-platform/3.5-android-app/) : Sử dụng công cụ như Expo, hoàn thành phát triển ứng dụng Android tích hợp Web/native | 🚧 | -| [Cao cấp 6: Phát triển đa nền tảng: Cách xây dựng ứng dụng iOS](docs/stage-3/cross-platform/3.6-ios-app/) : Sử dụng công cụ như Expo, hoàn thành phát triển ứng dụng iOS tích hợp Web/native | 🚧 | -| [Cao cấp 7: Cách xây dựng trang web cá nhân và blog học thuật của riêng bạn](docs/stage-3/personal-brand/3.7-personal-website-blog/) : Từ lựa chọn, xây dựng đến triển khai, xây dựng trang chủ online dài hạn trưng bày dự án cá nhân và kết quả học thuật | 🚧 | - -#### Phụ lục khả năng AI - -| Chương | Nội dung chính | Trạng thái | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | :--------- | -| [AI cao cấp 1: RAG là gì và nó hoạt động như thế nào](docs/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) : Hiểu có hệ thống nguyên lý RAG và kiến trúc phổ biến, cung cấp cơ sở truy xuất kiến thức cho ứng dụng phức tạp | ✅ | -| [AI cao cấp 2: RAG trung cấp-cao cấp và điều phối quy trình làm việc: Ví dụ LangGraph](docs/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) : Sử dụng công cụ như LangGraph để thiết kế quy trình làm việc đa bước và hệ thống RAG trung cấp-cao cấp | 🚧 | - -## 🛠️ Cách học - -- Theo khả năng cá nhân, đọc và thực hành có chọn lọc các chương liên quan, nếu có câu hỏi hãy đặt trong Issues. - -## 💻 Khởi động bài học này cục bộ - -### Phương pháp hiện đại - -Trong hộp thoại IDE AI (vscode, cursor, trae, v.v.), nhập prompt sau để khởi động bài học này: - -``` -Vui lòng giúp tôi chạy dịch vụ cục bộ của dự án này -``` - -### Phương pháp cũ - -1. npm install -2. npm run dev -3. Mở trình duyệt của bạn và truy cập `http://localhost:3000` để xem. - -## 🤝 Đóng góp - -- Nếu bạn phát hiện ra vấn đề hoặc nghĩ có cách nào để cải thiện dự án này, bạn có thể gửi Issue để phản hồi. Nếu sau khi gửi không ai trả lời, bạn có thể liên hệ [đội ngũ chăm sóc](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) để phản hồi và theo dõi~ -- Nếu bạn muốn đóng góp vào dự án này, bạn có thể gửi Pull Request, nếu sau khi gửi không ai trả lời, bạn có thể liên hệ [đội ngũ chăm sóc](https://github.com/datawhalechina/DOPMC/blob/main/OP.md) để phản hồi và theo dõi~ -- Nếu bạn rất quan tâm đến Datawhale và muốn bắt đầu một dự án mới, vui lòng làm theo [hướng dẫn dự án mã nguồn mở Datawhale](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)~ - -## 🙏 Cảm ơn mỗi người đóng góp - -- [散步-Lãnh đạo dự án](https://github.com/sanbuphy) (Thành viên Datawhale) -- Fang Ke-Giảng viên hướng dẫn (Thành viên Datawhale, Đại học Thanh Hoa) -- [Yerim Kang](https://github.com/yerim25)（Phần dự án thực tế-Đại học Thanh Hoa） -- Triệu Tri Lân（Phần dự án thực tế-Đại học Thanh Hoa） -- [Lý Nghi Tuyên](https://yixuan20.github.io/)（Thiết kế nghệ thuật trang-Đại học Thanh Hoa） -- Tất cả các bạn trong nhóm beta test AI Vibe Coding 101 đã cung cấp đề xuất và kinh nghiệm - -### Cảm ơn đặc biệt - -- Cảm ơn [@Sm1les](https://github.com/Sm1les) đã giúp đỡ và hỗ trợ dự án này -- Cảm ơn tất cả các nhà phát triển đã đóng góp vào dự án này ❤️ - -
- - - -
- -## 📧 Liên hệ với chúng tôi - -
-

Nếu bạn có câu hỏi, đề xuất, phàn nàn, hoặc muốn trao đổi, vui lòng quét mã QR bên dưới

- - -

Quét mã QR bên dưới để theo dõi tài khoản chính thức: Datawhale

- -
- -## 📄 GIẤY PHÉP - -
- - Creative Commons Giấy phép - -
-Tác phẩm này được cấp phép theo - - Creative Commons Ghi nhận - Phi thương mại - Chia sẻ tương tự 4.0 Quốc tế - -
- -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=datawhalechina/easy-vibe&type=date&legend=top-left)](https://www.star-history.com/#datawhalechina/easy-vibe&type=date&legend=top-left) +*(Xem chi tiết trong tài liệu trực tuyến hoặc repo chính)* diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.md index 9709b27..35461c7 100644 --- a/docs-readme/zh-TW/README.md +++ b/docs-readme/zh-TW/README.md @@ -4,23 +4,21 @@ 
 ███████╗ █████╗ ███████╗██╗   ██╗    ██╗   ██╗██╗██████╗ ███████╗
 ██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝    ██║   ██║██║██╔══██╗██╔════╝
-█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗
-██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝
+█████╗  ███████║███████╗ ╚████╔╝     ██║   ██║██║██████╔╝█████╗  
+██╔══╝  ██╔══██║╚════██║  ╚██╔╝      ╚██╗ ██╔╝██║██╔══██╗██╔══╝  
 ███████╗██║  ██║███████║   ██║        ╚████╔╝ ██║██████╔╝███████╗
 ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝         ╚═══╝  ╚═╝╚═════╝ ╚══════╝
-# Easy-Vibe: Learn Vibe Coding from 0 to 1 - -### _零基礎、專案制學習、建構第一個 AI 產品_ +# Easy-Vibe : 從 0 到 1 學習 Vibe Coding

- 📌 開始線上閱讀 (Start Reading Online) + 📌 在線閱讀 (Read Online) · ✨ 交互式教程 (Interactive Tutorial)

- 線上閱讀 · + 在線閱讀 · 學習地圖 · - 社群交流 + 社區交流

@@ -33,167 +31,351 @@

- 简体中文 - 繁體中文 - English - 日本語 - Español - Français - 한국어 - العربية - Tiếng_Việt - Deutsch + 简体中文 + 繁體中文 + English + 日本語 + Español + Français + Klingon + 한국어 + العربية + Türkçe + Tiếng_Việt + Deutsch + বাংলা

- -## 🚀 專案介紹 - -當你嘗試用AI寫程式碼，出錯不斷，時常想放棄，不清楚如何將程式真正上線 😢。 - -本教學專門設計，從0到1，帶你逐步掌握 Vibe Coding 技巧： - -- **第一階段**：從**小遊戲入門**到**Web 應用原型**，掌握 AI 編程基礎與產品思維 -- **第二階段**：學習**前後端開發與 AI 能力**相關的 vibecoding 技巧，完成完整應用 -- **第三階段**：掌握**多平台複雜應用**的建構方案，走向生產級應用 - -我們相信，掌握Vibe Coding並配合系統化訓練，一個人就能成為集前後端開發、AI 能力整合、產品設計於一身的開發者。 - -> **本專案主要面向三類學習者：** -> -> - **新手（普通人 / 產品與運營側）**：幫助非技術入門學習者聽懂關鍵概念，完成第一個產品原型。 -> - **初中級開發者（有一定基礎的學生和開發者）**：掌握前後端 vibe coding 與 AI 能力知識。 -> - **高級開發者（公司與初創、開源與獨立開發者）**：高級開發技巧、多平台開發。 - -### 📖 內容導航 - + + + + + + + + + + + + + +
+ +
+ 新手專屬學習地圖 +
+ 零基礎專屬指引，清晰規劃路徑，告別“學了忘” + 		+ +
+ 手把手圖文教程 +
+ 保姆級圖文詳解，如同私教在旁，跟着做就能學會 +
+ +
+ 沉浸式模擬編程 +
+ 虛擬鼠標自動導覽，帶你快速上手 IDE 核心用法 + 		+ +
+ 看得見的 AI 原理 +
+ 算法原理動畫化，一眼看懂 AI 如何“畫”出圖片 +
+ +
+ 像玩遊戲一樣學 RAG +
+ 獨家交互組件，點擊即可看清 RAG 數據流向 + 		+ +
+ 可視化終端原理 +
+ 命令行操作可視化，直觀展示後臺邏輯與原理 +
- Learning Map +

⭐ 歡迎 點擊此處 Star 加速更新 ❤️

-### 總附錄 +在 AI 時代，把想法變成產品的人，往往技術不是最強，而是最先邁出行動。 -[AI 能力詞典：常見 AI 核心概念與名詞、場景解釋](../docs/zh-cn/appendix/ai-capability-dictionary.md) +很多人即便有了 AI 助手，依然會被“代碼看不懂”、“環境不會配”勸退。**Easy-Vibe 為此而生。** 假設每個人都是零基礎，手把手帶你從寫出第一行代碼，到理解前後端邏輯，最後把產品上線。 -### 一、新手入門與產品原型 +- **面向人群**：初學者、產品經理、前後端 / 全站開發者 +- **主題**：AI 編程、全棧 Web 應用開發、AI Agent、工作流和 RAG 系統 -| 章节 | 關鍵內容 | 狀態 | -| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | -| [前言：學習地圖](../docs/zh-cn/stage-0/0.1-learning-map/index.md) | 整體學習路徑導覽 | ✅ | -| [初級一：AI 時代，會說話就會編程](../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | 通過貪吃蛇等案例初步感受 AI 編程的能力 | ✅ | -| [初級二：認識 AI IDE 工具](../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | 學會使用 IDE，在本地製作小遊戲 | ✅ | -| [初級三：動手做出原型](../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | 從需求分析、AI 生成單頁面，再到生成多頁面產品原型 | ✅ | -| [初級四：給原型加上 AI 能力](../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | 學會接入常見 AI 能力（文本、圖片、影片） | ✅ | -| [初級五：完整專案實戰](../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 模擬真實場景、接受用戶反饋迭代，完整化專案 | ✅ | -| [大作業：做一個完整的 Web 應用原型並展示](../docs/zh-cn/stage-1/1.5-final-project/index.md) | 完整實現應用，展示應用效果 | ✅ | +--- + +Easy-Vibe 通過以下幾個階段，帶你從 0 到 1： + +| 階段 | 核心技能 | 產出 | +| ------------ | -------------------------------- | ----------------------------------------- | +| **第一階段** | AI 編程入門、產品思維、原型設計 | 互動小遊戲、Web 應用原型（新手入門 & PM） | +| **第二階段** | 全棧開發、AI 集成、數據庫 | 完整的全棧 AI 應用 | +| **第三階段** | claude code 進階、小程序安卓開發 | 生產級多平台應用 | +| **附錄** | 幫你理解計算機、人工智能基礎概念 | 9 大知識領域、80+ 交互式專題 | + +## 🔥 News + +- **[2026-02-25]** 更新[附錄知識庫](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/)，涵蓋 9 大知識領域、80+ 交互式專題。 +- **[2026-01-27]** 新增 Android 和 iOS 平台應用開發教程。 +- **[2026-01-19]** 發佈 Prompt Engineering、AI 演進史、鑑權設計、Git 原理等一系列交互式演示組件，大幅提升可視化學習體驗。 + +
+Past News + +- **[2026-01-16]** 重構項目結構，正式確立“新手入門”章節，降低上手門檻。 +- **[2026-01-14]** 完成第一階段“產品原型構建”文檔的大規模更新。 +- **[2026-01-13]** 完成文檔架構重構，全面支持多語言 (i18n)。 +- **[2026-01-01]** 發佈項目核心學習地圖 (Learning Map)，明確學習路徑。 +
+ +### 📖 內容導覽 + +
+ Learning Map +
+ +### 📚 附錄知識庫 + +> 涵蓋 **9 大知識領域**、**80+ 交互式專題**，以動畫和可視化組件幫助你直觀理解從計算機底層到 AI 前沿的核心概念。 +> +> 👉 [查看完整附錄](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/) · [AI 能力詞典](https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary) + + + + + + + + + + + + + + + + + +
+ 💻 計算機基礎

+ • 從晶體管到 CPU
+ • 操作系統
+ • 數據的編碼、存儲與傳輸
+ • 網絡：兩臺電腦如何對話
+ • 數據結構
+ • 算法思維入門 + 		+ 🔧 開發工具

+ • Git：代碼的時光機
+ • 命令行與 Shell 腳本
+ • 包管理器
+ • 調試的藝術
+ • 正則表達式
+ • 環境變量與 PATH + 		+ 🌐 瀏覽器與前端

+ • JavaScript 語言深入
+ • 瀏覽器渲染管道
+ • 前端框架對比
+ • 圖形與動畫
+ • 網頁性能的度量與優化
+ • 前端工程化全貌 +
+ 🖥️ 服務器與後端

+ • HTTP 協議
+ • API 設計哲學
+ • 認證與授權體系
+ • 併發、異步與多線程
+ • 消息隊列與事件驅動
+ • 後端分層架構 + 		+ 📊 數據

+ • SQL
+ • 數據庫原理
+ • 數據埋點與用戶行為採集
+ • 數據分析基礎
+ • A/B 測試與實驗驅動
+ • 數據可視化與儀表盤 + 		+ 🏗️ 架構與系統設計

+ • 從單體到微服務的演進
+ • 分佈式系統的挑戰
+ • 高可用與容災
+ • 系統設計方法論 +
+ ☁️ 基礎設施與運維

+ • Docker 容器化
+ • Kubernetes 編排
+ • CI / CD 自動化
+ • 域名、DNS 與 HTTPS
+ • 監控、日誌與告警
+ • 基礎設施即代碼 + 		+ 🤖 人工智能

+ • 大語言模型的工作原理
+ • Transformer 與注意力機制
+ • RAG 架構
+ • AI Agent 與工具調用
+ • 提示詞工程
+ • 圖像生成原理 + 		+ 🎯 工程素養

+ • 代碼質量與重構
+ • 測試策略
+ • 設計模式
+ • 安全思維與攻防基礎
+ • 技術文檔寫作
+ • 開源協作 +
+ +### 一、零基礎入門 + +| 章節 | 關鍵內容 | 狀態 | +| :----------------------------------------------------------------------------------------------- | :------------------------------------------------ | :--- | +| [前言：學習地圖](../../docs/zh-cn/stage-0/0.1-learning-map/index.md) | 整體學習路徑導覽 | ✅ | +| [初級一：AI 時代，會說話就會編程](../../docs/zh-cn/stage-0/0.2-ai-capabilities-through-games/index.md) | 通過貪吃蛇等案例初步感受 AI 編程的能力 | ✅ | +| [初級二：尋找好想法](../../docs/zh-cn/stage-1/1.0-finding-great-idea/index.md) | 學會尋找和驗證產品想法，找到值得做的項目 | ✅ | +| [初級三：認識 AI IDE 工具](../../docs/zh-cn/stage-1/1.1-introduction-to-ai-ide/index.md) | 學會使用 IDE，在本地製作小遊戲 | ✅ | +| [初級四：動手做出原型](../../docs/zh-cn/stage-1/1.2-building-prototype/index.md) | 從需求分析、AI 生成單頁面，再到生成多頁面產品原型 | ✅ | +| [初級五：給原型加上 AI 能力](../../docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md) | 學會接入常見 AI 能力（文本、圖片、視頻） | ✅ | +| [初級六：完整項目實戰](../../docs/zh-cn/stage-1/1.4-complete-project-practice/index.md) | 模擬真實場景、接受用戶反饋迭代，完整化項目 | ✅ | #### 附錄：業務思維 -| 章節 | 關鍵內容 | 狀態 | -| :----------------------------------------------------------------------------------------------- | :------------------------------- | :--- | -| [附錄A：產品思維與方案設計](../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | 從零到一做產品需要考慮的思維框架 | ✅ | -| [附錄B：AI 行業應用場景參考 (B端)](../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | 了解 AI 在不同產業的應用場景 | ✅ | -| [附錄C：AI 消費場景靈感參考 (C端)](../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | 探索 AI 在消費級產品中的應用場景 | ✅ | +| 章節 | 關鍵內容 | 狀態 | +| :----------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [附錄A：產品思維與方案設計](../../docs/zh-cn/stage-1/appendix-a-product-thinking/index.md) | 從零到一做產品需要考慮的思維框架 | ✅ | +| [附錄B：AI 行業應用場景參考 (B端)](../../docs/zh-cn/stage-1/appendix-industry-scenarios/index.md) | 了解 AI 在不同產業的應用場景 | ✅ | +| [附錄C：AI 消費場景靈感參考 (C端)](../../docs/zh-cn/stage-1/appendix-c-consumer-scenarios/index.md) | 探索 AI 在消費級產品中的應用場景 | ✅ | #### 附錄：技術方案 -| 章節 | 關鍵內容 | 狀態 | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- | :--- | -| [附錄D：寫代碼時遇到錯誤怎麼辦](../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | vibe coding 中的常見錯誤及排查方法 | ✅ | -| [附錄E：七款 AI 編程工具對比](../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 對比測試主流 AI 編程平台 | ✅ | -| [附錄F：用設計和編程 Agent 設計網站](../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | 學習如何使用 AI 智能體協同工作 | ✅ | +| 章節 | 關鍵內容 | 狀態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | :--- | +| [附錄D：寫代碼時遇到錯誤怎麼辦](../../docs/zh-cn/stage-1/appendix-b-common-errors/index.md) | vibe coding 中的常見錯誤及排查方法 | ✅ | +| [附錄E：七款 AI 編程工具對比](../../docs/zh-cn/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 對比測試主流 AI 編程平台 | ✅ | +| [附錄F：用設計和編程 Agent 設計網站](../../docs/zh-cn/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | 學習如何使用 AI 智能體協同工作 | ✅ | -### 二、初中級開發工程師 +
+二、初中級開發工程師 #### 前端部分 -| 章节 | 關鍵內容 | 狀態 | -| :---------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | -| [前端零：使用 lovart 生產素材](../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | 學會用 lovart 批量生成人物、場景等視覺素材，為 UI 設計和前端開發提供素材基礎 | 🚧 | -| [前端一：Figma 與 MasterGo 入門](../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | 用設計工具梳理信息架構和頁面結構，為前端實現打基礎 | 🚧 | -| [前端二：建構第一個現代應用程式-UI 設計](../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | 基於設計稿完成組件化界面，實現從設計到代碼的第一條鏈路 | 🚧 | -| [前端三：參考 UI 設計規範與多產品 UI 設計](../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 圍繞統一主視覺擴展多產品界面，練習系統化設計能力 | 🚧 | -| [前端四：一起做霍格沃茨肖像](../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | 從 0 到 1 做出接入 AI 能力的前端應用，串聯設計與開發 | ✅ | +| 章節 | 關鍵內容 | 狀態 | +| :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- | +| [前端零：使用 lovart 生產素材](../../docs/zh-cn/stage-2/frontend/2.0-lovart-assets/) | 學會用 lovart 批量生成人物、場景等視覺素材，為 UI 設計和前端開發提供素材基礎 | 🚧 | +| [前端一：Figma 與 MasterGo 入門](../../docs/zh-cn/stage-2/frontend/2.1-figma-mastergo/) | 用設計工具梳理信息架構和頁面結構，為前端實現打基礎 | 🚧 | +| [前端二：構建第一個現代應用程序-UI 設計](../../docs/zh-cn/stage-2/frontend/2.2-ui-design/) | 基於設計稿完成組件化界面，實現從設計到代碼的第一條鏈路 | 🚧 | +| [前端三：參考 UI 設計規範與多產品 UI 設計](../../docs/zh-cn/stage-2/frontend/2.3-multi-product-ui/) | 圍繞統一主視覺擴展開多產品界面，練習系統化設計能力 | 🚧 | +| [前端四：一起做霍格沃茨畫像](../../docs/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits.md) | 從 0 到 1 做出接入 AI 能力的前端應用，串聯設計與開發 | ✅ | #### 後端與全棧部分 -| 章节 | 關鍵內容 | 狀態 | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | -| [後端一：什麼是 API](../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | 理解 HTTP 接口與請求響應模型，為後端整合與聯調做準備 | ✅ | -| [後端二：從數據庫到 Supabase](../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | 在 Supabase 上落地數據庫和 API，打通數據模型與前端頁面 | ✅ | -| [後端三：大模型輔助編寫接口代碼與接口文檔](../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | 用大模型協助生成接口與數據庫文檔及代碼，實現可讀可測的後端 | 🚧 | -| [後端四：Git 工作流](../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | 在 Git 工作流中管理代碼，進行版本控制和協作 | ✅ | -| [後端五：Zeabur 部署](../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | 將應用部署到 Zeabur 上線 | ✅ | -| [後端六：現代 CLI 開發工具](../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | 使用 CLI 類 AI 編程工具加速開發與調試，形成個人工程化工作流 | ✅ | -| [後端七：如何整合 Stripe 等收費系統](../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 接入支付系統，完成收費鏈路與基礎結算流程 | 🚧 | -| [大作業 1：建構第一個現代應用程式-全棧應用](../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | 綜合前端、後端與支付模塊，完成可上線的全棧 Web 應用 | 🚧 | -| [大作業 2：現代前端組件庫 + Trae 實戰](../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | 使用現代前端組件庫與 Trae，獨立完成可登錄註冊並支持收費的產品 | 🚧 | +| 章節 | 關鍵內容 | 狀態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- | +| [後端一：什麼是 API](../../docs/zh-cn/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md) | 理解 HTTP 接口與請求響應模型，為後端集成與聯調做準備 | ✅ | +| [後端二：從數據庫到 Supabase](../../docs/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase.md) | 在 Supabase 上落地數據庫和 API，打通數據模型與前端頁面 | ✅ | +| [後端三：大模型輔助編寫接口代碼與接口文檔](../../docs/zh-cn/stage-2/backend/2.3-ai-interface-code/) | 用大模型協助生成接口與數據庫文檔及代碼，實現可讀可測的後端 | 🚧 | +| [後端四：Git 工作流](../../docs/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github.md) | 在 Git 工作流中管理代碼，進行版本控制和協作 | ✅ | +| [後端五：Zeabur 部署](../../docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | 將應用部署到 Zeabur 上線 | ✅ | +| [後端六：現代 CLI 開發工具](../../docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | 使用 CLI 類 AI 編程工具加速開發與調試，形成個人工程化工作流 | ✅ | +| [後端七：如何集成 Stripe 等收費系統](../../docs/zh-cn/stage-2/backend/2.7-stripe-payment/) | 接入支付系統，完成收費鏈路與基礎結算流程 | 🚧 | +| [大作業 1：構建第一個現代應用程序-全棧應用](../../docs/zh-cn/stage-2/assignments/2.1-fullstack-app/) | 綜合前端、後端與支付模塊，完成可上線的全棧 Web 應用 | 🚧 | +| [大作業 2：現代前端組件庫 + Trae 實戰](../../docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/) | 使用現代前端組件庫與 Trae，獨立完成可登錄註冊並支持收費的產品 | 🚧 | #### AI 能力附錄 -| 章节 | 關鍵內容 | 狀態 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------- | :--- | -| [AI 一：Dify 入門與知識庫整合](../docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | 用 Dify Workflow 與基礎 RAG 搭建工具類產品，為後續應用升級打樣 | ✅ | -| [AI 二：學會查詢 AI 詞典與整合多模態 API](../docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 學會查找合適的模型與 API，並把文本、圖像等多模態能力接入產品 | 🚧 | +| 章節 | 關鍵內容 | 狀態 | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- | +| [AI 一：Dify 入門與知識庫集成](../../docs/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | 用 Dify Workflow 與基礎 RAG 搭建工具類產品，為後續應用升級打樣 | ✅ | +| [AI 二：學會查詢 AI 詞典與集成多模態 API](../../docs/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook.md) | 學會查找合適的模型與 API，並把文本、圖像等多模態能力接入產品 | 🚧 | -### 三、高級開發工程師 +
-| 章节 | 關鍵內容 | 狀態 | -| :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | -| [高級一：MCP 與 Claude Code Skills](../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | 通過 MCP 與 Skills 擴展 IDE 能力，把外部服務接成工具 | 🚧 | -| [高級二：如何讓 Coding Tools 長時間工作](../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 設計和配置長時間運行的任務，讓 Coding Tools 更穩定可靠 | 🚧 | -| [高級三：多平台開發：如何建構微信小程式](../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | 了解微信小程式生態，從官方模板到上線完成一個前端小程式 | ✅ | -| [高級四：多平台開發：如何建構微信小程式-包含後端](../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | 在小程式中接入數據庫與後端邏輯，打通完整業務閉環 | 🚧 | -| [高級五：多平台開發：如何建構安卓程式](../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | 使用 Expo 等工具，完成 Web/原生一體化的安卓應用開發 | 🚧 | -| [高級六：多平台開發：如何建構 iOS 程式](../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | 使用 Expo 等工具，完成 Web/原生一體化的 iOS 應用開發 | 🚧 | -| [高級七：如何建構屬於自己的個人網頁與學術博客](../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 從選型、搭建到部署，建構展示個人專案與學術成果的長久在線主頁 | 🚧 | +
+三、高級開發工程師 + +| 章節 | 關鍵內容 | 狀態 | +| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :--- | +| [高級一：MCP 與 Claude Code Skills](../../docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/) | 通過 MCP 與 Skills 擴展 IDE 能力，把外部服務接成工具 | 🚧 | +| [高級二：如何讓 Coding Tools 長時間工作](../../docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/) | 設計和配置長時間運行的任務，讓 Coding Tools 更穩定可靠 | 🚧 | +| [高級三：多平台開發：如何構建微信小程序](../../docs/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/) | 了解微信小程序生態，從官方模板到上線完成一個前端小程序 | ✅ | +| [高級四：多平台開發：如何構建微信小程序-包含後端](../../docs/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | 在小程序中接入數據庫與後端邏輯，打通完整業務閉環 | 🚧 | +| [高級五：多平台開發：如何構建安卓程序](../../docs/zh-cn/stage-3/cross-platform/3.5-android-app/) | 使用 Expo 等工具，完成 Web/原生一體化的安卓應用開發 | ✅ | +| [高級六：多平台開發：如何構建 iOS 程序](../../docs/zh-cn/stage-3/cross-platform/3.6-ios-app/) | 使用 Expo 等工具，完成 Web/原生一體化的 iOS 應用開發 | ✅ | +| [高級七：如何構建屬於自己的個人網頁與學術博客](../../docs/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/) | 從選型、搭建到部署，構建展示個人項目與學術成果的長久在線主頁 | 🚧 | #### AI 能力附錄 -| 章节 | 關鍵內容 | 狀態 | -| :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :--- | -| [高級 AI 一：什麼是 RAG 以及它如何工作](../docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | 系統理解 RAG 原理與常見架構，為複雜應用提供知識檢索基礎 | ✅ | -| [高級 AI 二：中高級 RAG 與工作流編排：以 LangGraph 為例](../docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | 使用 LangGraph 等工具設計多步工作流與中高級 RAG 系統 | 🚧 | +| 章節 | 關鍵內容 | 狀態 | +| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :--- | +| [高級 AI 一：什麼是 RAG 以及它如何工作](../../docs/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md) | 系統理解 RAG 原理與常見架構，為複雜應用提供知識檢索基礎 | ✅ | +| [高級 AI 二：中高級 RAG 與工作流編排：以 LangGraph 為例](../../docs/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | 使用 LangGraph 等工具設計多步工作流與中高級 RAG 系統 | 🚧 | + +
## 🛠️ 如何學習 - 根據個人能力，選擇性地閱讀和實踐相關章節，如果有問題歡迎 issue 提問。 -## 💻 本地啟動本課件 +## 💻 本地啓動本課件 ### 現代方案 -在 AI IDE 對話框（vscode、cursor、trae 等）中，輸入下列提示詞啟動本課件： +在 AI IDE 對話框（vscode、cursor、trae 等）中，輸入下列提示詞啓動本課件： ``` -請你幫我運行這個專案的本地服務 +請你幫我運行這個項目的本地服務 ``` ### 舊方案 1. npm install 2. npm run dev -3. 打開瀏覽器訪問 `http://localhost:5173` 即可查看。 +3. 打開瀏覽器訪問 `http://localhost:3000` 即可查看。 ## 🤝 參與貢獻 -- 如果你發現了一些問題，或者覺得任何可以改進本專案的地方，可以提 Issue 進行反饋。如果提完沒有人回復你可以聯系[保姆團隊](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同學進行反饋跟進~ -- 如果你想參與貢獻本專案，可以提 Pull Request，如果提完沒有人回復你可以聯系[保姆團隊](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同學進行反饋跟進~ -- 如果你對 Datawhale 很感興趣並想要發起一個新的專案，請按照[Datawhale 開源專案指南](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)進行操作即可~ +- 如果你發現了一些問題，或者覺得任何可以改進本项目的地方，可以提 Issue 進行反饋。如果提完沒有人回覆你可以聯繫[保姆團隊](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同學進行反饋跟進~ +- 如果你想參與貢獻本项目，可以提 Pull Request，如果提完沒有人回覆你可以聯繫[保姆團隊](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同學進行反饋跟進~ +- 如果你對 Datawhale 很感興趣並想要發起一個新的項目，請按照[Datawhale 開源項目指南](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)進行操作即可~ ## 🙏 感謝每位貢獻者 -- [散步-專案負責人](https://github.com/sanbuphy) (Datawhale成員) +- [散步-項目負責人](https://github.com/sanbuphy) (Datawhale成員) - 方可-指導老師（Datawhale成員, 清華大學） -- [Yerim Kang](https://github.com/yerim25)（實踐專案部分-清華大學） -- 趙芷霖（實踐專案部分-清華大學） +- [Yerim Kang](https://github.com/yerim25)（實踐項目部分-清華大學） +- 趙芷霖（實踐項目部分-清華大學） - [李亦萱](https://yixuan20.github.io/)（頁面美術設計-清華大學） +- 劉思怡（實踐項目部分-清華大學） - AI Vibe Coding 101 內測群完整給建議體驗的小夥伴們 ### 特別感謝 -- 感謝 [@Sm1les](https://github.com/Sm1les) 對本專案的幫助與支持 -- 感謝所有為本專案做出貢獻的開發者們 ❤️ +- 感謝 [@Sm1les](https://github.com/Sm1les) 對本項目的幫助與支持 +- 感謝所有為本项目做出貢獻的開發者們和支持點贊的朋友們 ❤️ + +
+ +

+ Stargazers +    + Forkers +

+ + + + + + + +
@@ -201,13 +383,13 @@
-## 📧 聯系我們 +## 📧 聯繫我們

如果有問題提建議吐槽，或者想要一起交流，請掃描下方二維碼

- + -

掃描下方二維碼關注公眾號：Datawhale

+

掃描下方二維碼關注公衆號：Datawhale

diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 40d9d85..f3d9a84 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -20,7 +20,7 @@ const localeMap = { lang: 'zh-CN', hreflang: 'zh-CN' }, - 'en-us': { + 'en': { ogLocale: 'en_US', twitterSite: '@datawhale', lang: 'en-US', @@ -203,6 +203,709 @@ const commonThemeConfig = { } } +const productManagerSidebarEn = [ + { + text: 'Getting Started', + collapsed: false, + items: [ + { text: 'Learning Map', link: '/en/stage-0/0.1-learning-map/' }, + { + text: 'AI Era: If You Can Speak, You Can Code', + link: '/en/stage-0/0.2-ai-capabilities-through-games/' + } + ] + }, + { + text: 'Product Prototype Skills', + collapsed: false, + items: [ + { + text: 'Master AI Programming Tools', + link: '/en/stage-1/1.1-introduction-to-ai-ide/' + }, + { + text: 'Find Great Ideas', + link: '/en/stage-1/1.0-finding-great-idea/' + }, + { + text: 'Build Product Prototypes', + link: '/en/stage-1/1.2-building-prototype/' + }, + { + text: 'Integrate AI Capabilities', + link: '/en/stage-1/1.3-integrating-ai-capabilities/' + }, + { + text: 'Complete Project Practice', + link: '/en/stage-1/1.4-complete-project-practice/' + } + ] + }, + { + text: 'Appendix: Business Thinking', + collapsed: false, + items: [ + { + text: 'Product Thinking and Solution Design', + link: '/en/stage-1/appendix-a-product-thinking/' + }, + { + text: 'AI Industry Application Scenarios (B-end)', + link: '/en/stage-1/appendix-industry-scenarios/' + }, + { + text: 'AI Consumer Scenarios Inspiration (C-end)', + link: '/en/stage-1/appendix-c-consumer-scenarios/' + } + ] + }, + { + text: 'Appendix: Technical Solutions', + collapsed: false, + items: [ + { + text: 'What to do if you encounter errors', + link: '/en/stage-1/appendix-b-common-errors/' + }, + { + text: 'Comparison of Seven AI Programming Tools', + link: '/en/stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial' + }, + { + text: 'Design Websites with Agents', + link: '/en/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents' + } + ] + } +] + +const stage2SidebarEn = [ + { + text: 'Frontend Development', + collapsed: false, + items: [ + { + text: 'Frontend 0: Lovart Assets', + link: '/zh-cn/stage-2/frontend/2.0-lovart-assets/' + }, + { + text: 'Frontend 1: Figma & MasterGo', + link: '/zh-cn/stage-2/frontend/2.1-figma-mastergo/' + }, + { + text: 'Frontend 2: UI Design', + link: '/zh-cn/stage-2/frontend/2.2-ui-design/' + }, + { + text: 'Frontend 3: UI Design Specs', + link: '/zh-cn/stage-2/frontend/2.3-multi-product-ui/' + }, + { + text: 'Frontend 4: Hogwarts Portraits', + link: '/zh-cn/stage-2/frontend/2.4-hogwarts-portraits/' + } + ] + }, + { + text: 'Backend & Full-Stack', + collapsed: false, + items: [ + { + text: 'Backend 1: What is API', + link: '/zh-cn/stage-2/backend/2.1-what-is-api/extra2/' + }, + { + text: 'Backend 2: Database & Supabase', + link: '/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/' + }, + { + text: 'Backend 3: AI-Assisted API Code', + link: '/zh-cn/stage-2/backend/2.3-ai-interface-code/' + }, + { + text: 'Backend 4: Git Workflow', + link: '/zh-cn/stage-2/backend/2.4-git-workflow/extra1/' + }, + { + text: 'Backend 5: Deployment', + link: '/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/' + }, + { + text: 'Backend 6: Modern CLI Tools', + link: '/zh-cn/stage-2/backend/2.6-modern-cli/extra7/' + }, + { + text: 'Backend 7: Stripe Payment', + link: '/zh-cn/stage-2/backend/2.7-stripe-payment/' + } + ] + }, + { + text: 'Assignments', + collapsed: false, + items: [ + { + text: 'Assignment 1: Full-Stack App', + link: '/zh-cn/stage-2/assignments/2.1-fullstack-app/' + }, + { + text: 'Assignment 2: UI Library & Trae', + link: '/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/' + } + ] + }, + { + text: 'AI Capabilities Appendix', + collapsed: false, + items: [ + { + text: 'AI 1: Dify & Knowledge Base', + link: '/zh-cn/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/' + }, + { + text: 'AI 2: AI Dictionary & Multimodal API', + link: '/zh-cn/stage-2/ai-capabilities/2.2-multimodal-api/extra3/' + } + ] + } +] + +const stage3SidebarEn = [ + { + text: 'Core Skills', + collapsed: false, + items: [ + { + text: 'Advanced 1: MCP & Claude Code Skills', + link: '/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/' + }, + { + text: 'Advanced 2: Long Running Tasks', + link: '/zh-cn/stage-3/core-skills/3.2-long-running-tasks/' + } + ] + }, + { + text: 'Multi-Platform', + collapsed: false, + items: [ + { + text: 'Advanced 3: WeChat Mini Program', + link: '/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/' + }, + { + text: 'Advanced 4: WeChat Mini Program (Backend)', + link: '/zh-cn/stage-3/cross-platform/3.4-wechat-miniprogram-backend/' + }, + { + text: 'Advanced 5: Android App - Compose', + link: '/zh-cn/stage-3/cross-platform/3.5-android-app/' + }, + { + text: 'Advanced 6: iOS App - SwiftUI', + link: '/zh-cn/stage-3/cross-platform/3.6-ios-app/' + } + ] + }, + { + text: 'Personal Brand', + collapsed: false, + items: [ + { + text: 'Advanced 7: Personal Website & Blog', + link: '/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/' + } + ] + }, + { + text: 'AI Advanced Appendix', + collapsed: false, + items: [ + { + text: 'AI Advanced 1: RAG Introduction', + link: '/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/' + }, + { + text: 'AI Advanced 2: LangGraph & Advanced RAG', + link: '/zh-cn/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/' + } + ] + } +] + +const appendixSidebarEn = [ + { + text: 'I. Computer Fundamentals', + collapsed: false, + items: [ + { + text: 'Full-Stack in Vibe Coding Era', + link: '/zh-cn/appendix/1-computer-fundamentals/vibe-coding-fullstack' + }, + { + text: 'Power On to Web Visit', + link: '/zh-cn/appendix/1-computer-fundamentals/power-on-to-web' + }, + { + text: 'Transistor to CPU', + link: '/zh-cn/appendix/1-computer-fundamentals/transistor-to-cpu' + }, + { + text: 'Computer Organization', + link: '/zh-cn/appendix/1-computer-fundamentals/computer-organization' + }, + { + text: 'Operating Systems', + link: '/zh-cn/appendix/1-computer-fundamentals/operating-systems' + }, + { + text: 'Data Encoding & Storage', + link: '/zh-cn/appendix/1-computer-fundamentals/data-encoding-storage' + }, + { + text: 'Computer Networks', + link: '/zh-cn/appendix/1-computer-fundamentals/computer-networks' + }, + { + text: 'Data Structures', + link: '/zh-cn/appendix/1-computer-fundamentals/data-structures' + }, + { + text: 'Algorithm Thinking', + link: '/zh-cn/appendix/1-computer-fundamentals/algorithm-thinking' + }, + { + text: 'Programming Languages', + link: '/zh-cn/appendix/1-computer-fundamentals/programming-languages' + }, + { + text: 'Compilers Intro', + link: '/zh-cn/appendix/1-computer-fundamentals/compilers' + }, + { + text: 'Type Systems Intro', + link: '/zh-cn/appendix/1-computer-fundamentals/type-systems' + } + ] + }, + { + text: 'II. Tools & Environment', + collapsed: false, + items: [ + { + text: 'IDE Basics', + link: '/zh-cn/appendix/2-development-tools/ide-basics' + }, + { + text: 'Command Line & Shell', + link: '/zh-cn/appendix/2-development-tools/command-line-shell' + }, + { + text: 'Git: Code Time Machine', + link: '/zh-cn/appendix/2-development-tools/git-version-control' + }, + { + text: 'Env Vars & PATH', + link: '/zh-cn/appendix/2-development-tools/environment-path' + }, + { + text: 'Ports & Localhost', + link: '/zh-cn/appendix/2-development-tools/ports-localhost' + }, + { + text: 'SSH & Key Auth', + link: '/zh-cn/appendix/2-development-tools/ssh-authentication' + }, + { + text: 'Package Managers', + link: '/zh-cn/appendix/2-development-tools/package-managers' + }, + { + text: 'Art of Debugging', + link: '/zh-cn/appendix/2-development-tools/debugging-art/' + }, + { + text: 'Regex', + link: '/zh-cn/appendix/2-development-tools/regex' + } + ] + }, + { + text: 'III. Browser & Frontend', + collapsed: false, + items: [ + { + text: 'JavaScript Deep Dive', + link: '/zh-cn/appendix/3-browser-and-frontend/javascript-deep-dive' + }, + { + text: 'TypeScript Intro', + link: '/zh-cn/appendix/3-browser-and-frontend/typescript' + }, + { + text: 'Frontend Frameworks', + link: '/zh-cn/appendix/3-browser-and-frontend/frontend-frameworks' + }, + { + text: 'Browser as OS', + link: '/zh-cn/appendix/3-browser-and-frontend/browser-as-os' + }, + { + text: 'Rendering Pipeline', + link: '/zh-cn/appendix/3-browser-and-frontend/browser-as-os-rendering' + }, + { + text: 'HTML / CSS Layout', + link: '/zh-cn/appendix/3-browser-and-frontend/html-css-layout' + }, + { + text: 'JS Runtime', + link: '/zh-cn/appendix/3-browser-and-frontend/javascript-runtime' + }, + { + text: 'Nature of Frameworks', + link: '/zh-cn/appendix/3-browser-and-frontend/frontend-framework-nature' + }, + { + text: 'State Management', + link: '/zh-cn/appendix/3-browser-and-frontend/state-management' + }, + { + text: 'Routing & Navigation', + link: '/zh-cn/appendix/3-browser-and-frontend/routing-navigation' + }, + { + text: 'Graphics & Animation', + link: '/zh-cn/appendix/3-browser-and-frontend/graphics-animation' + }, + { + text: 'Real-time Comm', + link: '/zh-cn/appendix/3-browser-and-frontend/realtime-communication' + }, + { + text: 'Web Performance', + link: '/zh-cn/appendix/3-browser-and-frontend/web-performance' + }, + { + text: 'Frontend Engineering', + link: '/zh-cn/appendix/3-browser-and-frontend/frontend-engineering' + }, + { + text: 'Project Architecture', + link: '/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture' + }, + { + text: 'A11y & i18n', + link: '/zh-cn/appendix/3-browser-and-frontend/a11n-i18n' + } + ] + }, + { + text: 'IV. Server & Backend', + collapsed: false, + items: [ + { + text: 'Backend Languages', + link: '/zh-cn/appendix/4-server-and-backend/backend-languages' + }, + { + text: 'Client Languages', + link: '/zh-cn/appendix/4-server-and-backend/client-languages' + }, + { + text: 'Cross-platform Solutions', + link: '/zh-cn/appendix/4-server-and-backend/cross-platform' + }, + { + text: 'HTTP Protocol', + link: '/zh-cn/appendix/4-server-and-backend/http-protocol' + }, + { + text: 'Request Journey', + link: '/zh-cn/appendix/4-server-and-backend/request-journey' + }, + { + text: 'Web Frameworks', + link: '/zh-cn/appendix/4-server-and-backend/web-frameworks' + }, + { + text: 'API Intro', + link: '/zh-cn/appendix/4-server-and-backend/api-intro' + }, + { + text: 'API Design Philosophy', + link: '/zh-cn/appendix/4-server-and-backend/api-design' + }, + { + text: 'Serialization', + link: '/zh-cn/appendix/4-server-and-backend/serialization' + }, + { + text: 'Auth & Authorization', + link: '/zh-cn/appendix/4-server-and-backend/auth-authorization' + }, + { + text: 'Concurrency & Async', + link: '/zh-cn/appendix/4-server-and-backend/concurrency-async' + }, + { + text: 'Caching Strategies', + link: '/zh-cn/appendix/4-server-and-backend/caching' + }, + { + text: 'Message Queues', + link: '/zh-cn/appendix/4-server-and-backend/message-queues' + }, + { + text: 'Async Task Queues', + link: '/zh-cn/appendix/4-server-and-backend/async-task-queues' + }, + { + text: 'Rate Limiting', + link: '/zh-cn/appendix/4-server-and-backend/rate-limiting-backpressure' + }, + { + text: 'Search Engine Principles', + link: '/zh-cn/appendix/4-server-and-backend/search-engines' + }, + { + text: 'File Storage', + link: '/zh-cn/appendix/4-server-and-backend/file-storage' + }, + { + text: 'Backend Architecture', + link: '/zh-cn/appendix/4-server-and-backend/backend-layered-architecture' + }, + { + text: 'Project Architecture', + link: '/zh-cn/appendix/4-server-and-backend/backend-project-architecture' + }, + { + text: 'DSL Intro', + link: '/zh-cn/appendix/4-server-and-backend/domain-specific-languages' + } + ] + }, + { + text: 'V. Data', + collapsed: false, + items: [ + { + text: 'Database Fundamentals', + link: '/zh-cn/appendix/5-data/database-fundamentals' + }, + { + text: 'Data Models Panorama', + link: '/zh-cn/appendix/5-data/data-models' + }, + { + text: 'Data Tracking', + link: '/zh-cn/appendix/5-data/data-tracking' + }, + { + text: 'Data Analysis', + link: '/zh-cn/appendix/5-data/data-analysis' + }, + { + text: 'A/B Testing', + link: '/zh-cn/appendix/5-data/ab-testing' + }, + { + text: 'Data Visualization', + link: '/zh-cn/appendix/5-data/data-visualization' + }, + { + text: 'Data Governance', + link: '/zh-cn/appendix/5-data/data-governance' + } + ] + }, + { + text: 'VI. Architecture', + collapsed: false, + items: [ + { + text: 'Monolith to Microservices', + link: '/zh-cn/appendix/6-architecture-and-system-design/monolith-to-microservices' + }, + { + text: 'Distributed Systems', + link: '/zh-cn/appendix/6-architecture-and-system-design/distributed-systems' + }, + { + text: 'HA & Disaster Recovery', + link: '/zh-cn/appendix/6-architecture-and-system-design/high-availability' + }, + { + text: 'System Design', + link: '/zh-cn/appendix/6-architecture-and-system-design/system-design-methodology' + } + ] + }, + { + text: 'VII. Infrastructure', + collapsed: false, + items: [ + { + text: 'Linux Basics', + link: '/zh-cn/appendix/7-infrastructure-and-operations/linux-basics' + }, + { + text: 'Docker Containers', + link: '/zh-cn/appendix/7-infrastructure-and-operations/docker-containers' + }, + { + text: 'Kubernetes', + link: '/zh-cn/appendix/7-infrastructure-and-operations/kubernetes' + }, + { + text: 'CI / CD', + link: '/zh-cn/appendix/7-infrastructure-and-operations/ci-cd' + }, + { + text: 'Domain, DNS & HTTPS', + link: '/zh-cn/appendix/7-infrastructure-and-operations/dns-https' + }, + { + text: 'Load Balancing', + link: '/zh-cn/appendix/7-infrastructure-and-operations/load-balancing-gateway' + }, + { + text: 'Gateway & Reverse Proxy', + link: '/zh-cn/appendix/7-infrastructure-and-operations/gateway-proxy' + }, + { + text: 'Cloud Platforms', + link: '/zh-cn/appendix/7-infrastructure-and-operations/cloud-platforms' + }, + { + text: 'IAM', + link: '/zh-cn/appendix/7-infrastructure-and-operations/cloud-iam' + }, + { + text: 'Storage & CDN', + link: '/zh-cn/appendix/7-infrastructure-and-operations/cloud-storage-cdn' + }, + { + text: 'IaC', + link: '/zh-cn/appendix/7-infrastructure-and-operations/infrastructure-as-code' + }, + { + text: 'Monitoring & Logging', + link: '/zh-cn/appendix/7-infrastructure-and-operations/monitoring-logging' + }, + { + text: 'Incident Response', + link: '/zh-cn/appendix/7-infrastructure-and-operations/incident-response' + } + ] + }, + { + text: 'VIII. Artificial Intelligence', + collapsed: false, + items: [ + { + text: 'AI History & Concepts', + link: '/zh-cn/appendix/8-artificial-intelligence/ai-history' + }, + { + text: 'Neural Networks', + link: '/zh-cn/appendix/8-artificial-intelligence/neural-networks' + }, + { + text: 'Transformer & Attention', + link: '/zh-cn/appendix/8-artificial-intelligence/transformer-attention' + }, + { + text: 'LLM Principles', + link: '/zh-cn/appendix/8-artificial-intelligence/llm-principles' + }, + { + text: 'Prompt Engineering', + link: '/zh-cn/appendix/8-artificial-intelligence/prompt-engineering' + }, + { + text: 'Context Engineering', + link: '/zh-cn/appendix/8-artificial-intelligence/context-engineering' + }, + { + text: 'Multimodal Models', + link: '/zh-cn/appendix/8-artificial-intelligence/multimodal-models' + }, + { + text: 'Image Generation', + link: '/zh-cn/appendix/8-artificial-intelligence/image-generation' + }, + { + text: 'Speech Synthesis', + link: '/zh-cn/appendix/8-artificial-intelligence/speech-synthesis-recognition' + }, + { + text: 'Embedding & Vector Search', + link: '/zh-cn/appendix/8-artificial-intelligence/embedding-vector-retrieval' + }, + { + text: 'RAG Architecture', + link: '/zh-cn/appendix/8-artificial-intelligence/rag' + }, + { + text: 'AI Agent & Tools', + link: '/zh-cn/appendix/8-artificial-intelligence/ai-agents' + }, + { + text: 'AI Protocols (MCP)', + link: '/zh-cn/appendix/8-artificial-intelligence/ai-protocols' + }, + { + text: 'Fine-tuning & Deployment', + link: '/zh-cn/appendix/8-artificial-intelligence/model-finetuning-deployment' + }, + { + text: 'AI Native Design', + link: '/zh-cn/appendix/8-artificial-intelligence/ai-native-app-design' + }, + { + text: 'AI Dictionary', + link: '/zh-cn/appendix/8-artificial-intelligence/ai-capability-dictionary' + } + ] + }, + { + text: 'IX. Engineering Excellence', + collapsed: false, + items: [ + { + text: 'Code Quality', + link: '/zh-cn/appendix/9-engineering-excellence/code-quality-refactoring' + }, + { + text: 'Testing Strategies', + link: '/zh-cn/appendix/9-engineering-excellence/testing-strategies' + }, + { + text: 'Design Patterns', + link: '/zh-cn/appendix/9-engineering-excellence/design-patterns' + }, + { + text: 'Security Thinking', + link: '/zh-cn/appendix/9-engineering-excellence/security-thinking' + }, + { + text: 'Technical Writing', + link: '/zh-cn/appendix/9-engineering-excellence/technical-writing' + }, + { + text: 'Open Source', + link: '/zh-cn/appendix/9-engineering-excellence/open-source-collaboration' + }, + { + text: 'Tech Selection', + link: '/zh-cn/appendix/9-engineering-excellence/technology-selection' + } + ] + } +] + const productManagerSidebar = [ { text: '新手入门', @@ -288,6 +991,15 @@ export default defineConfig({ base: base, ignoreDeadLinks: true, + // Vite 配置 + vite: { + server: { + watch: { + ignored: ['**/docs/.vitepress/dist/**'] + } + } + }, + // Sitemap 配置 sitemap: { hostname: 'https://datawhalechina.github.io/easy-vibe', @@ -726,7 +1438,7 @@ export default defineConfig({ link: '/zh-cn/appendix/3-browser-and-frontend/frontend-engineering' }, { - text: '前端项目架构设计', + text: '前端项目文件目录设计', link: '/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture' }, { @@ -812,7 +1524,7 @@ export default defineConfig({ link: '/zh-cn/appendix/4-server-and-backend/backend-layered-architecture' }, { - text: '后端项目架构设计', + text: '后端项目文件目录设计', link: '/zh-cn/appendix/4-server-and-backend/backend-project-architecture' }, { @@ -1045,15 +1757,15 @@ export default defineConfig({ }, // 英文 - 'en-us': { - label: 'English (US)', + 'en': { + label: 'English', lang: 'en-US', - link: '/en-us/', + link: '/en/', title: 'Easy-Vibe Tutorial', description: 'Learn Vibe Coding from Zero to Advanced - Master AI programming with Claude Code, Cursor, and other AI IDE tools', head: getSeoHead( - 'en-us', + 'en', 'Easy-Vibe Tutorial', 'Learn Vibe Coding from Zero to Advanced - Master AI programming with Claude Code, Cursor, and other AI IDE tools' ), @@ -1064,23 +1776,28 @@ export default defineConfig({ label: 'On this page' }, nav: [ - { text: 'Home', link: '/en-us/' }, + { text: 'Home', link: '/en/' }, { text: 'Novice & PM', - link: '/en-us/stage-0/' + link: '/en/stage-0/' }, { text: 'Full-Stack Development', - link: '/en-us/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'Advanced Development', - link: '/en-us/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'Appendix', link: '/en-us/appendix/' } + { text: 'Appendix', link: '/zh-cn/appendix/index' } ], - // TODO: Add English sidebar when content is ready - sidebar: {} + sidebar: { + '/en/stage-0/': productManagerSidebarEn, + '/en/stage-1/': productManagerSidebarEn, + '/en/stage-2/': stage2SidebarEn, + '/en/stage-3/': stage3SidebarEn, + '/en/appendix/': appendixSidebarEn + } } }, @@ -1107,17 +1824,17 @@ export default defineConfig({ { text: 'ホーム', link: '/ja-jp/' }, { text: '初心者とPM', - link: '/ja-jp/stage-0/' + link: '/zh-cn/stage-0/' }, { text: 'フルスタック開発', - link: '/ja-jp/stage-2/' + link: '/zh-cn/stage-2/' }, { text: '上級開発', - link: '/ja-jp/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: '付録', link: '/ja-jp/appendix/' } + { text: '付録', link: '/zh-cn/appendix/' } ], // TODO: Add Japanese sidebar when content is ready sidebar: {} @@ -1145,17 +1862,17 @@ export default defineConfig({ { text: '首頁', link: '/zh-tw/' }, { text: '新手與產品原型', - link: '/zh-tw/stage-0/' + link: '/zh-cn/stage-0/' }, { text: '初中級開發', - link: '/zh-tw/stage-2/' + link: '/zh-cn/stage-2/' }, { text: '高級開發', - link: '/zh-tw/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: '附錄', link: '/zh-tw/appendix/' } + { text: '附錄', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1180,16 +1897,16 @@ export default defineConfig({ }, nav: [ { text: '홈', link: '/ko-kr/' }, - { text: '초보자 & PM', link: '/ko-kr/stage-0/' }, + { text: '초보자 & PM', link: '/zh-cn/stage-0/' }, { text: '풀스택 개발', - link: '/ko-kr/stage-2/' + link: '/zh-cn/stage-2/' }, { text: '고급 개발', - link: '/ko-kr/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: '부록', link: '/ko-kr/appendix/' } + { text: '부록', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1216,17 +1933,17 @@ export default defineConfig({ { text: 'Inicio', link: '/es-es/' }, { text: 'Principiante y PM', - link: '/es-es/stage-0/' + link: '/zh-cn/stage-0/' }, { text: 'Desarrollo Full Stack', - link: '/es-es/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'Desarrollo Avanzado', - link: '/es-es/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'Apéndice', link: '/es-es/appendix/' } + { text: 'Apéndice', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1251,16 +1968,16 @@ export default defineConfig({ }, nav: [ { text: 'Accueil', link: '/fr-fr/' }, - { text: 'Débutant & PM', link: '/fr-fr/stage-0/' }, + { text: 'Débutant & PM', link: '/zh-cn/stage-0/' }, { text: 'Développement Full Stack', - link: '/fr-fr/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'Développement Avancé', - link: '/fr-fr/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'Annexe', link: '/fr-fr/appendix/' } + { text: 'Annexe', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1285,16 +2002,16 @@ export default defineConfig({ }, nav: [ { text: 'Start', link: '/de-de/' }, - { text: 'Anfänger & PM', link: '/de-de/stage-0/' }, + { text: 'Anfänger & PM', link: '/zh-cn/stage-0/' }, { text: 'Full Stack Entwicklung', - link: '/de-de/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'Fortgeschrittene Entwicklung', - link: '/de-de/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'Anhang', link: '/de-de/appendix/' } + { text: 'Anhang', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1321,17 +2038,17 @@ export default defineConfig({ { text: 'الرئيسية', link: '/ar-sa/' }, { text: 'مبتدأ & PM', - link: '/ar-sa/stage-0/' + link: '/zh-cn/stage-0/' }, { text: 'تطوير Full Stack', - link: '/ar-sa/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'تطوير متقدم', - link: '/ar-sa/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'ملحق', link: '/ar-sa/appendix/' } + { text: 'ملحق', link: '/zh-cn/appendix/' } ], sidebar: {} } @@ -1358,17 +2075,17 @@ export default defineConfig({ { text: 'Trang chủ', link: '/vi-vn/' }, { text: 'Người mới & PM', - link: '/vi-vn/stage-0/' + link: '/zh-cn/stage-0/' }, { text: 'Phát triển Full Stack', - link: '/vi-vn/stage-2/' + link: '/zh-cn/stage-2/' }, { text: 'Phát triển Nâng cao', - link: '/vi-vn/stage-3/' + link: '/zh-cn/stage-3/' }, - { text: 'Phụ lục', link: '/vi-vn/appendix/' } + { text: 'Phụ lục', link: '/zh-cn/appendix/' } ], sidebar: {} } diff --git a/docs/.vitepress/theme/components/AppendixFlowMap.vue b/docs/.vitepress/theme/components/AppendixFlowMap.vue new file mode 100644 index 0000000..a9c4e86 --- /dev/null +++ b/docs/.vitepress/theme/components/AppendixFlowMap.vue @@ -0,0 +1,390 @@ + + + + + \ No newline at end of file diff --git a/docs/.vitepress/theme/components/HomeFeatures.vue b/docs/.vitepress/theme/components/HomeFeatures.vue index cdf9bf3..8e4e086 100644 --- a/docs/.vitepress/theme/components/HomeFeatures.vue +++ b/docs/.vitepress/theme/components/HomeFeatures.vue @@ -220,7 +220,7 @@ const i18n = { btn: '>_ Start' } }, - 'en-us': { + 'en': { nav: { title: 'Easy-Vibe Tutorial', home: 'Home', @@ -231,27 +231,27 @@ const i18n = { start: 'Start Learning' }, stage1: { - cat: 'Stage 1 · Novice & PM', + cat: 'Stage 1 · Getting Started', title: 'Zero to Hero,
Be Your Own PM.', - sub: 'No CS background needed. Just speak your idea, and AI will turn it into high-fidelity web prototypes.', + sub: 'No CS background needed. Just speak your ideas—AI will turn them into high-fidelity web prototypes.', cards: [ { - title: 'AI Product Manager', - desc: 'From idea to prototype, just by speaking.', - sub: 'Non-tech friendly', - link: '/en-us/stage-0/' + title: 'Learning Map', + desc: 'Understand the complete learning path from zero to full-stack development.', + sub: 'All Ages Friendly', + link: '/en/stage-0/0.1-learning-map/' }, { title: 'Gamified Intro', - desc: 'Build Snake, Tetris, and break the fear of code.', - sub: 'Learn by playing', - link: '/en-us/stage-0/' + desc: 'Experience the magic of AI programming by building games like Snake.', + sub: 'Learn by Playing', + link: '/en/stage-0/0.2-ai-capabilities-through-games/' }, { title: 'Vibe Coding', - desc: 'Master the core of AI coding: Prompt Engineering & Context.', + desc: 'Master the core of AI coding: From product ideas to interactive prototypes.', sub: 'Core Mindset', - link: '/en-us/stage-0/' + link: '/en/stage-0/' } ] }, @@ -259,25 +259,25 @@ const i18n = { cat: 'Stage 2 · Junior/Mid Dev', title: 'Go Full Stack,
Build Real Apps.', - sub: 'Master frontend-backend separation. Build commercial-grade projects with DB, API, and complex interactions.', + sub: 'Master frontend-backend separation and build commercial-grade projects with DB and API.', cards: [ { title: 'Full Stack', headline: 'Frontend & Backend.', desc: 'From DB design to API and components, build a modern web app completely.', - link: '/en-us/stage-2/' + link: '/zh-cn/stage-2/assignments/2.1-fullstack-app/' }, { title: 'Real Projects', headline: 'No Toy Code.', desc: 'Deep dive into Auth, Storage, File Uploads and core business logic.', - link: '/en-us/stage-2/' + link: '/zh-cn/stage-2/backend/2.2-database-supabase/chapter5/' }, { title: 'Deployment', headline: 'Show the World.', desc: 'Server config, DNS, CI/CD. The last mile of product delivery.', - link: '/en-us/stage-2/' + link: '/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/' } ] }, @@ -290,22 +290,22 @@ const i18n = { { title: 'WeChat Mini-app', desc: 'Cross-platform dev, reaching millions of users.', - link: '/en-us/stage-3/' + link: '/zh-cn/stage-3/cross-platform/3.3-wechat-miniprogram/' }, { title: 'AI Native Apps', desc: 'RAG, Agent. Explore the limits of LLMs.', - link: '/en-us/stage-3/' + link: '/zh-cn/stage-3/ai-advanced/3.a1-rag-introduction/' }, { title: 'Complex Arch', - desc: 'High concurrency, High availability architecture design.', - link: '/en-us/stage-3/' + desc: 'Architecture design for high concurrency and stable AI tasks.', + link: '/zh-cn/stage-3/core-skills/3.2-long-running-tasks/' }, { title: 'Personal Brand', desc: 'Build your own website and academic blog.', - link: '/en-us/stage-3/' + link: '/zh-cn/stage-3/personal-brand/3.7-personal-website-blog/' } ] }, @@ -318,62 +318,62 @@ const i18n = { { title: 'AI History', desc: 'Milestones in AI evolution.', - link: '/en-us/appendix/ai-evolution' + link: '/zh-cn/appendix/8-artificial-intelligence/ai-history' }, { title: 'Prompt Eng', desc: 'Master AI communication skills.', - link: '/en-us/appendix/prompt-engineering' + link: '/zh-cn/appendix/8-artificial-intelligence/prompt-engineering' }, { title: 'LLM Intro', desc: 'Understanding Large Language Models.', - link: '/en-us/appendix/llm-intro' + link: '/zh-cn/appendix/8-artificial-intelligence/llm-principles' }, { title: 'AI Agents', desc: 'Autonomous decision-making AI.', - link: '/en-us/appendix/agent-intro' + link: '/zh-cn/appendix/8-artificial-intelligence/ai-agents' }, { title: 'Web Basics', desc: 'HTML/CSS/JS fundamentals.', - link: '/en-us/appendix/web-basics' + link: '/zh-cn/appendix/3-browser-and-frontend/javascript-deep-dive' }, { title: 'Frontend Evo', desc: 'Evolution of frontend tech stack.', - link: '/en-us/appendix/frontend-evolution' + link: '/zh-cn/appendix/3-browser-and-frontend/frontend-frameworks' }, { title: 'Backend Arch', desc: 'From monolith to microservices.', - link: '/en-us/appendix/backend-evolution' + link: '/zh-cn/appendix/4-server-and-backend/backend-layered-architecture' }, { title: 'Backend Lang', desc: 'Choosing the right tech stack.', - link: '/en-us/appendix/backend-languages' + link: '/zh-cn/appendix/4-server-and-backend/backend-languages' }, { title: 'Database', desc: 'Core principles of data storage.', - link: '/en-us/appendix/database-intro' + link: '/zh-cn/appendix/5-data/database-fundamentals' }, { title: 'API Design', desc: 'Designing robust interfaces.', - link: '/en-us/appendix/api-intro' + link: '/zh-cn/appendix/4-server-and-backend/api-intro' }, { title: 'Git', desc: 'Version control mastery.', - link: '/en-us/appendix/git-intro' + link: '/zh-cn/appendix/2-development-tools/git-version-control' }, { title: 'Networks', desc: 'Protocols and communication.', - link: '/en-us/appendix/computer-networks' + link: '/zh-cn/appendix/1-computer-fundamentals/computer-networks' } ] }, @@ -1374,12 +1374,12 @@ const i18n = { import { computed } from 'vue' const t = computed(() => { const code = lang.value ? lang.value.toLowerCase() : 'zh-cn' - return i18n[code] || i18n['en-us'] + return i18n[code] || i18n['en'] }) const locales = [ { code: 'zh-cn', text: '简体中文' }, - { code: 'en-us', text: 'English' }, + { code: 'en', text: 'English' }, { code: 'ja-jp', text: '日本語' }, { code: 'zh-tw', text: '繁體中文' }, { code: 'ko-kr', text: '한국어' }, @@ -1699,7 +1699,7 @@ const appendixCards = [ {{ t.footer.btn }} diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue index bd3b282..d8a5414 100644 --- a/docs/.vitepress/theme/components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue @@ -155,7 +155,7 @@ diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompileVsInterpretDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompileVsInterpretDemo.vue index 0c46b5e..3a1da8a 100644 --- a/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompileVsInterpretDemo.vue +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompileVsInterpretDemo.vue @@ -47,12 +47,16 @@ diff --git a/docs/.vitepress/theme/components/appendix/data-governance/DataLineageDemo.vue b/docs/.vitepress/theme/components/appendix/data-governance/DataLineageDemo.vue new file mode 100644 index 0000000..a40dc24 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data-governance/DataLineageDemo.vue @@ -0,0 +1,138 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data-governance/DataQualityDemo.vue b/docs/.vitepress/theme/components/appendix/data-governance/DataQualityDemo.vue new file mode 100644 index 0000000..ea8f23c --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data-governance/DataQualityDemo.vue @@ -0,0 +1,266 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data-visualization/ChartTypeSelectorDemo.vue b/docs/.vitepress/theme/components/appendix/data-visualization/ChartTypeSelectorDemo.vue new file mode 100644 index 0000000..ef09c98 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data-visualization/ChartTypeSelectorDemo.vue @@ -0,0 +1,131 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data-visualization/DashboardLayoutDemo.vue b/docs/.vitepress/theme/components/appendix/data-visualization/DashboardLayoutDemo.vue new file mode 100644 index 0000000..a027792 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data-visualization/DashboardLayoutDemo.vue @@ -0,0 +1,134 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/distributed-systems/CAPTheoremDemo.vue b/docs/.vitepress/theme/components/appendix/distributed-systems/CAPTheoremDemo.vue new file mode 100644 index 0000000..83c201a --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/distributed-systems/CAPTheoremDemo.vue @@ -0,0 +1,120 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/distributed-systems/ConsistencyModelsDemo.vue b/docs/.vitepress/theme/components/appendix/distributed-systems/ConsistencyModelsDemo.vue new file mode 100644 index 0000000..b4d37fb --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/distributed-systems/ConsistencyModelsDemo.vue @@ -0,0 +1,132 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/distributed-systems/DistributedChallengesDemo.vue b/docs/.vitepress/theme/components/appendix/distributed-systems/DistributedChallengesDemo.vue new file mode 100644 index 0000000..d726e56 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/distributed-systems/DistributedChallengesDemo.vue @@ -0,0 +1,215 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/docker-containers/DockerArchitectureDemo.vue b/docs/.vitepress/theme/components/appendix/docker-containers/DockerArchitectureDemo.vue new file mode 100644 index 0000000..7c9ac6e --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/docker-containers/DockerArchitectureDemo.vue @@ -0,0 +1,184 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/docker-containers/DockerLifecycleDemo.vue b/docs/.vitepress/theme/components/appendix/docker-containers/DockerLifecycleDemo.vue new file mode 100644 index 0000000..64ab8ac --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/docker-containers/DockerLifecycleDemo.vue @@ -0,0 +1,178 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/high-availability/AvailabilityCalculatorDemo.vue b/docs/.vitepress/theme/components/appendix/high-availability/AvailabilityCalculatorDemo.vue new file mode 100644 index 0000000..86fd2aa --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/high-availability/AvailabilityCalculatorDemo.vue @@ -0,0 +1,87 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/high-availability/FailoverStrategyDemo.vue b/docs/.vitepress/theme/components/appendix/high-availability/FailoverStrategyDemo.vue new file mode 100644 index 0000000..5c59846 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/high-availability/FailoverStrategyDemo.vue @@ -0,0 +1,143 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/kubernetes/K8sArchitectureDemo.vue b/docs/.vitepress/theme/components/appendix/kubernetes/K8sArchitectureDemo.vue new file mode 100644 index 0000000..b09e9cc --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/kubernetes/K8sArchitectureDemo.vue @@ -0,0 +1,183 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/kubernetes/K8sWorkloadsDemo.vue b/docs/.vitepress/theme/components/appendix/kubernetes/K8sWorkloadsDemo.vue new file mode 100644 index 0000000..131f036 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/kubernetes/K8sWorkloadsDemo.vue @@ -0,0 +1,235 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/linux-basics/LinuxCommandDemo.vue b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxCommandDemo.vue new file mode 100644 index 0000000..9ce0db2 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxCommandDemo.vue @@ -0,0 +1,168 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/linux-basics/LinuxFileSystemDemo.vue b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxFileSystemDemo.vue new file mode 100644 index 0000000..ac2f8a6 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxFileSystemDemo.vue @@ -0,0 +1,119 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/linux-basics/LinuxPermissionsDemo.vue b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxPermissionsDemo.vue new file mode 100644 index 0000000..6c1d65c --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/linux-basics/LinuxPermissionsDemo.vue @@ -0,0 +1,234 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/monolith-to-microservices/ArchEvolutionDemo.vue b/docs/.vitepress/theme/components/appendix/monolith-to-microservices/ArchEvolutionDemo.vue new file mode 100644 index 0000000..9ccdb24 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/monolith-to-microservices/ArchEvolutionDemo.vue @@ -0,0 +1,158 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/neural-networks/NetworkArchitectureDemo.vue b/docs/.vitepress/theme/components/appendix/neural-networks/NetworkArchitectureDemo.vue new file mode 100644 index 0000000..8777bf8 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/neural-networks/NetworkArchitectureDemo.vue @@ -0,0 +1,222 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/neural-networks/NetworkLayersDemo.vue b/docs/.vitepress/theme/components/appendix/neural-networks/NetworkLayersDemo.vue new file mode 100644 index 0000000..be83e04 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/neural-networks/NetworkLayersDemo.vue @@ -0,0 +1,132 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/neural-networks/NeuronDemo.vue b/docs/.vitepress/theme/components/appendix/neural-networks/NeuronDemo.vue new file mode 100644 index 0000000..3db9dc5 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/neural-networks/NeuronDemo.vue @@ -0,0 +1,202 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/system-design-methodology/CapacityEstimationDemo.vue b/docs/.vitepress/theme/components/appendix/system-design-methodology/CapacityEstimationDemo.vue new file mode 100644 index 0000000..a94d5ef --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/system-design-methodology/CapacityEstimationDemo.vue @@ -0,0 +1,183 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/appendix/system-design-methodology/SystemDesignStepsDemo.vue b/docs/.vitepress/theme/components/appendix/system-design-methodology/SystemDesignStepsDemo.vue new file mode 100644 index 0000000..6dd2bf9 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/system-design-methodology/SystemDesignStepsDemo.vue @@ -0,0 +1,199 @@ + + + + + + diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index 5d905e4..87d5e26 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -206,15 +206,15 @@ import LearningStrategyDemo from './components/appendix/computer-fundamentals/Le import VibeCodingFlowDemo from './components/appendix/computer-fundamentals/VibeCodingFlowDemo.vue' import PowerOnDemo from './components/appendix/computer-fundamentals/PowerOnDemo.vue' import BootProcessDemo from './components/appendix/computer-fundamentals/BootProcessDemo.vue' -import BiosUefiDemo from './components/appendix/computer-fundamentals/BiosUefiDemo.vue' -import BiosUefiInteractiveDemo from './components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue' -import AppLaunchDemo from './components/appendix/computer-fundamentals/AppLaunchDemo.vue' -import DesktopDemo from './components/appendix/computer-fundamentals/DesktopDemo.vue' -import OSBootInteractiveDemo from './components/appendix/computer-fundamentals/OSBootInteractiveDemo.vue' -import BrowserArchitectureDemo from './components/appendix/computer-fundamentals/BrowserArchitectureDemo.vue' -import URLRequestDemo from './components/appendix/computer-fundamentals/URLRequestDemo.vue' -import RenderingDemo from './components/appendix/computer-fundamentals/RenderingDemo.vue' -import FullProcessDemo from './components/appendix/computer-fundamentals/FullProcessDemo.vue' +// import BiosUefiDemo from './components/appendix/computer-fundamentals/BiosUefiDemo.vue' +// import BiosUefiInteractiveDemo from './components/appendix/computer-fundamentals/BiosUefiInteractiveDemo.vue' +// import AppLaunchDemo from './components/appendix/computer-fundamentals/AppLaunchDemo.vue' +// import DesktopDemo from './components/appendix/computer-fundamentals/DesktopDemo.vue' +// import OSBootInteractiveDemo from './components/appendix/computer-fundamentals/OSBootInteractiveDemo.vue' +// import BrowserArchitectureDemo from './components/appendix/computer-fundamentals/BrowserArchitectureDemo.vue' +// import URLRequestDemo from './components/appendix/computer-fundamentals/URLRequestDemo.vue' +// import RenderingDemo from './components/appendix/computer-fundamentals/RenderingDemo.vue' +// import FullProcessDemo from './components/appendix/computer-fundamentals/FullProcessDemo.vue' // Data Encoding Components import GarbledTextDemo from './components/appendix/data-encoding/GarbledTextDemo.vue' @@ -762,27 +762,73 @@ import IncidentCommandDemo from './components/appendix/incident-response/Inciden import AlertEscalationDemo from './components/appendix/incident-response/AlertEscalationDemo.vue' import PostmortemDemo from './components/appendix/incident-response/PostmortemDemo.vue' -// Async Task Queues Components -import AsyncTaskFlowDemo from './components/appendix/async-task-queues/AsyncTaskFlowDemo.vue' -import TaskWorkerDemo from './components/appendix/async-task-queues/TaskWorkerDemo.vue' -import TaskRetryDemo from './components/appendix/async-task-queues/TaskRetryDemo.vue' -import AsyncComparisonDemo from './components/appendix/async-task-queues/AsyncComparisonDemo.vue' +// // Async Task Queues Components +// import AsyncTaskFlowDemo from './components/appendix/async-task-queues/AsyncTaskFlowDemo.vue' +// import TaskWorkerDemo from './components/appendix/async-task-queues/TaskWorkerDemo.vue' +// import TaskRetryDemo from './components/appendix/async-task-queues/TaskRetryDemo.vue' +// import AsyncComparisonDemo from './components/appendix/async-task-queues/AsyncComparisonDemo.vue' -// File Storage Components -import FileStorageTypeDemo from './components/appendix/file-storage/FileStorageTypeDemo.vue' -import FileUploadFlowDemo from './components/appendix/file-storage/FileUploadFlowDemo.vue' -import CDNAccelerationDemo from './components/appendix/file-storage/CDNAccelerationDemo.vue' +// // File Storage Components +// import FileStorageTypeDemo from './components/appendix/file-storage/FileStorageTypeDemo.vue' +// import FileUploadFlowDemo from './components/appendix/file-storage/FileUploadFlowDemo.vue' +// import CDNAccelerationDemo from './components/appendix/file-storage/CDNAccelerationDemo.vue' -// Rate Limiting Components -import RateLimitAlgorithmDemo from './components/appendix/rate-limiting/RateLimitAlgorithmDemo.vue' -import BackpressureDemo from './components/appendix/rate-limiting/BackpressureDemo.vue' +// // Rate Limiting Components +// import RateLimitAlgorithmDemo from './components/appendix/rate-limiting/RateLimitAlgorithmDemo.vue' +// import BackpressureDemo from './components/appendix/rate-limiting/BackpressureDemo.vue' // Search Engines Components Registration import InvertedIndexDemo from './components/appendix/search-engines/InvertedIndexDemo.vue' import SearchRelevanceDemo from './components/appendix/search-engines/SearchRelevanceDemo.vue' +// Monolith to Microservices Components +import ArchEvolutionDemo from './components/appendix/monolith-to-microservices/ArchEvolutionDemo.vue' + +// High Availability Components +import AvailabilityCalculatorDemo from './components/appendix/high-availability/AvailabilityCalculatorDemo.vue' +import FailoverStrategyDemo from './components/appendix/high-availability/FailoverStrategyDemo.vue' + +// Distributed Systems Components +import CAPTheoremDemo from './components/appendix/distributed-systems/CAPTheoremDemo.vue' +import ConsistencyModelsDemo from './components/appendix/distributed-systems/ConsistencyModelsDemo.vue' +import DistributedChallengesDemo from './components/appendix/distributed-systems/DistributedChallengesDemo.vue' + +// System Design Methodology Components +import SystemDesignStepsDemo from './components/appendix/system-design-methodology/SystemDesignStepsDemo.vue' +import CapacityEstimationDemo from './components/appendix/system-design-methodology/CapacityEstimationDemo.vue' + +// Data Visualization Components +import ChartTypeSelectorDemo from './components/appendix/data-visualization/ChartTypeSelectorDemo.vue' +import DashboardLayoutDemo from './components/appendix/data-visualization/DashboardLayoutDemo.vue' + +// Data Governance Components +import DataQualityDemo from './components/appendix/data-governance/DataQualityDemo.vue' +import DataGovernanceFrameworkDemo from './components/appendix/data-governance/DataGovernanceFrameworkDemo.vue' +import DataLineageDemo from './components/appendix/data-governance/DataLineageDemo.vue' + +// Linux Basics Components +import LinuxFileSystemDemo from './components/appendix/linux-basics/LinuxFileSystemDemo.vue' +import LinuxCommandDemo from './components/appendix/linux-basics/LinuxCommandDemo.vue' +import LinuxPermissionsDemo from './components/appendix/linux-basics/LinuxPermissionsDemo.vue' + +// Docker Containers Components +import DockerArchitectureDemo from './components/appendix/docker-containers/DockerArchitectureDemo.vue' +import DockerLifecycleDemo from './components/appendix/docker-containers/DockerLifecycleDemo.vue' + +// Kubernetes Components +import K8sArchitectureDemo from './components/appendix/kubernetes/K8sArchitectureDemo.vue' +import K8sWorkloadsDemo from './components/appendix/kubernetes/K8sWorkloadsDemo.vue' + +// Neural Networks Components +import NeuronDemo from './components/appendix/neural-networks/NeuronDemo.vue' +import NetworkLayersDemo from './components/appendix/neural-networks/NetworkLayersDemo.vue' +import NetworkArchitectureDemo from './components/appendix/neural-networks/NetworkArchitectureDemo.vue' + // Project Architecture Components -import ArchitectureComparisonDemo from './components/appendix/project-architecture/ArchitectureComparisonDemo.vue' +import ProjectArchitectureComparisonDemo from './components/appendix/project-architecture/ArchitectureComparisonDemo.vue' + +// Appendix Navigation Component +import AppendixFlowMap from './components/AppendixFlowMap.vue' export default { extends: DefaultTheme, @@ -995,15 +1041,15 @@ export default { app.component('VibeCodingFlowDemo', VibeCodingFlowDemo) app.component('PowerOnDemo', PowerOnDemo) app.component('BootProcessDemo', BootProcessDemo) - app.component('BiosUefiDemo', BiosUefiDemo) - app.component('BiosUefiInteractiveDemo', BiosUefiInteractiveDemo) - app.component('AppLaunchDemo', AppLaunchDemo) - app.component('DesktopDemo', DesktopDemo) - app.component('OSBootInteractiveDemo', OSBootInteractiveDemo) - app.component('BrowserArchitectureDemo', BrowserArchitectureDemo) - app.component('URLRequestDemo', URLRequestDemo) - app.component('RenderingDemo', RenderingDemo) - app.component('FullProcessDemo', FullProcessDemo) + // app.component('BiosUefiDemo', BiosUefiDemo) + // app.component('BiosUefiInteractiveDemo', BiosUefiInteractiveDemo) + // app.component('AppLaunchDemo', AppLaunchDemo) + // app.component('DesktopDemo', DesktopDemo) + // app.component('OSBootInteractiveDemo', OSBootInteractiveDemo) + // app.component('BrowserArchitectureDemo', BrowserArchitectureDemo) + // app.component('URLRequestDemo', URLRequestDemo) + // app.component('RenderingDemo', RenderingDemo) + // app.component('FullProcessDemo', FullProcessDemo) // Data Encoding Components Registration app.component('GarbledTextDemo', GarbledTextDemo) @@ -1564,27 +1610,73 @@ export default { app.component('AlertEscalationDemo', AlertEscalationDemo) app.component('PostmortemDemo', PostmortemDemo) - // Async Task Queues Components Registration - app.component('AsyncTaskFlowDemo', AsyncTaskFlowDemo) - app.component('TaskWorkerDemo', TaskWorkerDemo) - app.component('TaskRetryDemo', TaskRetryDemo) - app.component('AsyncComparisonDemo', AsyncComparisonDemo) + // // Async Task Queues Components Registration + // app.component('AsyncTaskFlowDemo', AsyncTaskFlowDemo) + // app.component('TaskWorkerDemo', TaskWorkerDemo) + // app.component('TaskRetryDemo', TaskRetryDemo) + // app.component('AsyncComparisonDemo', AsyncComparisonDemo) - // File Storage Components Registration - app.component('FileStorageTypeDemo', FileStorageTypeDemo) - app.component('FileUploadFlowDemo', FileUploadFlowDemo) - app.component('CDNAccelerationDemo', CDNAccelerationDemo) + // // File Storage Components Registration + // app.component('FileStorageTypeDemo', FileStorageTypeDemo) + // app.component('FileUploadFlowDemo', FileUploadFlowDemo) + // app.component('CDNAccelerationDemo', CDNAccelerationDemo) - // Rate Limiting Components Registration - app.component('RateLimitAlgorithmDemo', RateLimitAlgorithmDemo) - app.component('BackpressureDemo', BackpressureDemo) + // // Rate Limiting Components Registration + // app.component('RateLimitAlgorithmDemo', RateLimitAlgorithmDemo) + // app.component('BackpressureDemo', BackpressureDemo) // Search Engines Components Registration app.component('InvertedIndexDemo', InvertedIndexDemo) app.component('SearchRelevanceDemo', SearchRelevanceDemo) + // Data Visualization Components Registration + app.component('ChartTypeSelectorDemo', ChartTypeSelectorDemo) + app.component('DashboardLayoutDemo', DashboardLayoutDemo) + + // Data Governance Components Registration + app.component('DataQualityDemo', DataQualityDemo) + app.component('DataGovernanceFrameworkDemo', DataGovernanceFrameworkDemo) + app.component('DataLineageDemo', DataLineageDemo) + + // Distributed Systems Components Registration + app.component('CAPTheoremDemo', CAPTheoremDemo) + app.component('ConsistencyModelsDemo', ConsistencyModelsDemo) + app.component('DistributedChallengesDemo', DistributedChallengesDemo) + + // High Availability Components Registration + app.component('AvailabilityCalculatorDemo', AvailabilityCalculatorDemo) + app.component('FailoverStrategyDemo', FailoverStrategyDemo) + + // Monolith to Microservices Components Registration + app.component('ArchEvolutionDemo', ArchEvolutionDemo) + + // System Design Methodology Components Registration + app.component('SystemDesignStepsDemo', SystemDesignStepsDemo) + app.component('CapacityEstimationDemo', CapacityEstimationDemo) + + // Docker Containers Components Registration + app.component('DockerArchitectureDemo', DockerArchitectureDemo) + app.component('DockerLifecycleDemo', DockerLifecycleDemo) + + // Linux Basics Components Registration + app.component('LinuxFileSystemDemo', LinuxFileSystemDemo) + app.component('LinuxCommandDemo', LinuxCommandDemo) + app.component('LinuxPermissionsDemo', LinuxPermissionsDemo) + + // Kubernetes Components Registration + app.component('K8sArchitectureDemo', K8sArchitectureDemo) + app.component('K8sWorkloadsDemo', K8sWorkloadsDemo) + + // Neural Networks Components Registration + app.component('NeuronDemo', NeuronDemo) + app.component('NetworkLayersDemo', NetworkLayersDemo) + app.component('NetworkArchitectureDemo', NetworkArchitectureDemo) + // Project Architecture Components Registration - app.component('ArchitectureComparisonDemo', ArchitectureComparisonDemo) + app.component('ProjectArchitectureComparisonDemo', ProjectArchitectureComparisonDemo) + + // Appendix Navigation Component Registration + app.component('AppendixFlowMap', AppendixFlowMap) }, setup() { const route = useRoute() diff --git a/docs/en-us/stage-0/index.md b/docs/en-us/stage-0/index.md deleted file mode 100644 index 732375b..0000000 --- a/docs/en-us/stage-0/index.md +++ /dev/null @@ -1,66 +0,0 @@ -# Novice & Product Prototype - -Welcome to the **AI Product Manager** stage! This is the starting point of the Easy-Vibe tutorial, designed for learners with zero programming background. - -## What You Will Learn - -In this stage, you will start from scratch and master the Vibe Coding workflow to become a super individual capable of independent product design. - -### Getting Started - -Suitable for product managers, operations staff, and non-technical backgrounds. Understand AI programming logic through games and build confidence: - - - - - - -### Product Manager - -Master the Vibe Coding workflow. Learn to break down requirements and independently complete high-fidelity web application prototypes: - - - - - - - - -## Who Is This For - -- Product managers and operations staff with zero programming background -- Entrepreneurs who want to quickly validate ideas -- Non-technical people interested in AI programming -- Designers looking to enhance their prototyping skills - -## Learning Path - -``` -Getting Started → Product Manager Basics → AI Capability Integration → Complete Project Practice -``` - -Ready to start your AI programming journey? Click the left navigation to begin learning! diff --git a/docs/en-us/appendix/index.md b/docs/en/appendix/index.md similarity index 100% rename from docs/en-us/appendix/index.md rename to docs/en/appendix/index.md diff --git a/docs/en-us/assets b/docs/en/assets similarity index 100% rename from docs/en-us/assets rename to docs/en/assets diff --git a/docs/en-us/index.md b/docs/en/index.md similarity index 91% rename from docs/en-us/index.md rename to docs/en/index.md index 5aea566..6ebf4bf 100644 --- a/docs/en-us/index.md +++ b/docs/en/index.md @@ -17,10 +17,10 @@ hero: actions: - theme: brand text: Start Learning - link: /en-us/stage-0/ + link: /en/stage-0/ - theme: alt text: Course Outline - link: /en-us/stage-0/ + link: /en/stage-0/ --- diff --git a/docs/en-us/public/logo.png b/docs/en/public/logo.png similarity index 100% rename from docs/en-us/public/logo.png rename to docs/en/public/logo.png diff --git a/docs/en-us/public/style.css b/docs/en/public/style.css similarity index 100% rename from docs/en-us/public/style.css rename to docs/en/public/style.css diff --git a/docs/en/stage-0/0.1-learning-map/index.md b/docs/en/stage-0/0.1-learning-map/index.md new file mode 100644 index 0000000..da8b285 --- /dev/null +++ b/docs/en/stage-0/0.1-learning-map/index.md @@ -0,0 +1,259 @@ +--- +title: 'From Idea to AI Product - Easy-Vibe Learning Roadmap' +description: 'Complete roadmap for learning AI programming: from zero basics to full-stack development. Master AI IDE tools like Vibe Coding, Claude Code, and Cursor, and learn product thinking, full-stack development, and AI capability integration.' +--- + +# From Idea to AI Product + +In the past, building software had a high barrier: you had to understand programming and algorithms and have years of project experience. +Now it's different. As long as you have an idea, AI can help you write the code. + +This is a huge change: **Programming languages are becoming natural languages**. + +The emergence of Large Language Models (LLMs) has turned development from a "technical expert's exclusive" into a tool everyone can use. What used to be the hardest part—"how to write code"—is now replaced by the new hardest part: "**What do you want to do?**" + +> **What is Vibe Coding?** +> Simply put, it's "programming by speaking." Vibe coding means you can rely solely on conversing with AI instead of writing code directly to complete a programming project. + +Of course, letting AI write code is just the first step. To make a truly usable product, you will still encounter these questions: +- How to let AI write clean, maintainable code? +- How to piece together scattered code into a runnable application? +- How to make the application truly go live and be used by people? +- How to put AI capabilities like text generation and image recognition into your product? + +These questions will find answers in this course. + +Whether you are a student, teacher, doctor, worker, or any common person who knows nothing about technology—you don't need to learn programming for years first; in two weeks, you can make a runnable, demonstrable product prototype. + +| Your Identity | This Course Can Help You | +|---------|-------------| +| Student | Assignments, competitions, entrepreneurship; do projects yourself without asking for help | +| Professional | Automate repetitive work, improve efficiency, and even develop side hustles | +| Product Manager / Designer | Ideas no longer stay on paper; quickly make Demos to show bosses/clients | +| Entrepreneur / SME Owner | Validate ideas at low cost; make an MVP without spending tens of thousands on outsourcing | +| Teacher / Educator | Make teaching tools, courseware, and automated questions to improve teaching efficiency | +| Doctor / Lawyer / Professional | Automate professional processes and build your own efficiency tools | +| Anyone | Use AI to solve specific problems in life/work, making the impossible possible | + +In the AI era, execution and ideas are always more important than technology. + +## Growth Path: From "Using AI" to "Making AI Products" + +
+
+
🎮
+

Getting Started

+

Experience AI Programming

+
+ Snake Mini-game + Zero Basics to Start + Vibe Coding First Experience + Generate in Minutes +
+
+
+ +
+
+
🛠️
+

Stage One

+

Product Manager / Operations

+
+ AI IDE (Cursor/Claude) + Requirement Deconstruction & Prototype + Integrate AI Capabilities + Full Demo Development +
+
+
+
💻
+

Stage Two

+

Junior-Mid Developer / Indie Dev

+
+ Figma to Code + Supabase Database + Stripe Payment Integration + Dify Knowledge Base +
+
+
+
🚀
+

Stage Three

+

Senior Developer / Architect

+
+ Web/Mini-program/Multi-platform + MCP Advanced Tools + RAG & LangGraph + Senior Engineer Thinking +
+
+
+ + + +Through this complete learning path, you will gain: + +- **Vibe Coding Development Ability:** Effortlessly use vibe coding thinking and AI coding tools to increase development efficiency several times. No longer need to memorize syntax, but learn how to guide AI to generate high-quality code. +- **Full-stack Development Skills:** From UI design to front-end implementation, from database design to API development, and from local development to cloud deployment, master the full technology stack of modern Web applications. +- **AI Capability Integration:** Learn to call various multimodal AI APIs and seamlessly integrate AI capabilities like text, images, and voice into your applications, building intelligent products through technologies like RAG. +- **Product Thinking and Operations Ability:** From user research to demand deconstruction, from MVP design to product iteration, and from payment integration to user management, form a complete product development and operation closed loop. + +# What Can You Do After Learning? + +## Stage One: Build Your First Product Prototype + +This stage is suitable for students with zero programming foundation or those who only know a little but are not confident. You don't need to learn a lot of theoretical knowledge first, but follow the steps directly and learn how to use AI tools to write code in the process. + +**After learning, you can**: +- Independently complete a web application using AI programming tools +- Turn product ideas into clickable, interactive prototypes +- Add AI functions to the prototype (e.g., text-to-image, intelligent dialogue) +- Know how to troubleshoot and solve problems when encountering errors + +Simply put, you can make something "runnable and demonstrable to others." + +We can first experience AI programming through mini-games, then learn how to use AI programming tools to help you write code and fix errors. Then start from simple pages and gradually make interactive multi-page applications, adding AI functions like text-to-image and intelligent dialogue. Finally, independently complete a full project so that your creativity can truly have the possibility of landing. + +# Why Use Project-Based Training? + +> **Real-world Challenges** +> +> The reason is simple: based on the state of most students now, directly entering the workplace might make it difficult to move an inch under the "social beatings" of real projects and bosses/clients. More common scenarios in the real world are: + +> Your mentor / boss: We want to do xxx, the goal is to achieve yyy effect. +> +> Documentation? Ready-made frameworks? Detailed requirement specifications? Often they don't exist. + +Many tasks in real work are essentially solving problems never seen before in a highly uncertain environment: requirements are vague, boundaries are changing, no one tells you the standard answer, and you need to look up information, do experiments, build prototypes, iterate continuously, and finally give a "runnable, usable, and launchable" solution. + +What this course wants to do is give you a "simulated social beating" in advance in a relatively safe environment: + +- Force you to practice deconstructing problems, designing solutions, and finding information yourself through seemingly difficult project tasks. +- Allow you to learn to read, understand, and transform a medium-to-large codebase through scaffolds and code that are not so "idiot-proof." +- Let you experience the complete process of a real product from 0 to 1 through the complete closed loop from idea to launch. + +In the short term, this kind of training is indeed torturous; but in the long term, it will greatly improve your competitiveness in job searching and career development: you will be more able to handle things, more able to find breakthroughs in uncertain environments, and more capable of turning AI into real landing products instead of staying in the "playing with demos" stage. + +# The Art of Questioning: An Essential Skill in the AI Era + +In the AI era, questioning is also a "basic skill." For the same code and the same error, **how you ask almost determines what kind of answer AI can give**: whether it's talking broadly or giving implementable modifications step by step. + +**Develop Good Habits**: Treat "asking AI" as part of the daily development flow: ask immediately when you don't understand or get stuck. + +## Why is this an Essential Skill? + +- **Real life rarely has complete documentation**: Most of the time you face unclear requirements, half-finished code, and scattered error messages. +- **AI is your tutor + colleague by your side**: Those who can ask questions can turn it into "high-quality pair programming." +- **Ability upper limit is determined by communication**: The more you can provide key information and the more you can constrain the output format, the more usable the answer will be. + +**Common Misconception**: Asking just "Why error?" usually only gets a bunch of guesses. Only by filling in the context will you get an executable solution. + +## How to "Feed" Information to AI: Screenshots vs Copy-Paste + +Both methods are fine, but for different purposes: + +| Method | Applicable Scenarios | Key Requirements | +| ------------ | ----------------------------------------- | ----------------------------------------- | +| **Copy-Paste** | Error stacks, logs, code, configuration, API returns | Be as complete as possible; don't just take one line of keywords | +| **Screenshot** | UI layout issues, interaction anomalies, can't find buttons in tools | Screenshot full screen + highlight key areas, preferably with a line of text description | + +::: danger ⚠️ Important Prerequisite +**Not all AI support image input.** Communication via screenshots requires AI to have multimodal capabilities (i.e., the ability to understand and analyze images). Current AIs that support image input include: Claude (Anthropic), GPT-4V/GPT-4o (OpenAI), Gemini (Google), and some Chinese models like Tongyi Qianwen, Wenxin Yiyan, etc. + +**If the AI you are using does not support image input**, screenshots will not be recognized. In this case, please switch to copy-pasting text for communication. +::: + +## Prompt Tips to Make AI "Explain Well" + +If you don't just want the answer, but want to "learn" the answer. Using instructions like the following can significantly improve the quality of explanation: + +> **Learning Question Examples** +> +> - "Please explain this concept clearly in 5 sentences first, and then ask me a few questions to verify if I understood it correctly." +> - "Please explain this error message in detail; I don't understand why the error occurred." + +# I've been persistent for a long time but still can't handle it, I want to give up + +Maybe your method of persistence is wrong. Don't hold on alone in the dark; you can come and talk to the authors and teaching assistants: frankly state the methods you have tried, the specific stuck points you encountered, and your current state of mind. Many times, just a slight adjustment in direction or adding a key knowledge point can keep you moving forward. + +# I feel some designs of the tutorial are unreasonable + +You are welcome to contact the author at any time, submit an issue, or give feedback directly in the group/class. We very much hope to work with you to polish this set of tutorials to be better and better: wherever it's unclear, wherever the experience is broad, or wherever it makes you waste effort, you can point it out frankly. The more real and specific the feedback, the more it can help newcomers avoid pitfalls. + +# Reference + +- [Nanjing University Computer Science and Technology Department Computer System Fundamentals Course Experiment](https://nju-projectn.github.io/ics-pa-gitbook/ics2025/) diff --git a/docs/en/stage-0/0.2-ai-capabilities-through-games/index.md b/docs/en/stage-0/0.2-ai-capabilities-through-games/index.md new file mode 100644 index 0000000..2bbb285 --- /dev/null +++ b/docs/en/stage-0/0.2-ai-capabilities-through-games/index.md @@ -0,0 +1,743 @@ +# Primary 1: AI Era, If You Can Speak, You Can Code + +This is a **project-based learning** tutorial. We encourage you to follow the steps one by one and try to reproduce the results. +Don't worry about making mistakes or modifying the content. We always believe you can do it. Please always remember: + +
+
+ Completion is more important than perfection 🐣 +
+
+ + + +## Chapter Outline + + + +If you don't know how to program at all, or only know the basics, this chapter is for you. We will start from the very beginning: using conversations to have AI write code for you, without needing to memorize syntax or set up environments. It will run right in your browser. + +You will personally create your first running program—a Snake game that can "eat words, write poems, and draw". Through this practical exercise, you will experience what AI programming is really like: AI is not replacing your thinking, but rather, you speak your ideas, and AI helps you implement them. + +All creation starts from 0 to 1. We are glad to pass each bit of confidence and professionalism to you. For you, execution is all you need. + + + +
+ + + +
+ +## 1. Dilemmas and Opportunities for Ordinary People + +Many people have a bunch of product ideas in their heads: a small tool to help manage finances, a webpage to record a child's growth, or even a mini-game. But the thought of having to write code or find a programmer often discourages them directly. + +After the emergence of AI, for the first time, ordinary people have a completely new possibility: you don't need to know how to write code, you just need to learn how to clearly tell AI what you want. [Data from GitHub Copilot](https://www.wearetenet.com/blog/github-copilot-usage-data-statistics) shows that over 15 million developers are using AI-assisted programming, with an average of 46% of code being AI-generated! In Java projects, this proportion can reach 61%. + + + + + + +
+
55%
+
Speed Increase
+
+ + +
+
2.4 Days
+
Task Time (from 9.6)
+
+ + +
+
81%
+
Day-1 Install Rate
+
+ + +
+
96%
+
Suggestion Adoption
+
+ + + +
+ What is truly exciting is the leap in efficiency: developers' task completion speed increased by 55%. Code that originally took 9.6 days to deliver can now be done in just 2.4 days. This visible improvement shows that AI is no longer just an "optional feature" but is becoming an indispensable assistant in the development workflow. The adoption rate data confirms this: on the day they granted access, 81% of developers installed and started using it immediately; among them, 96% started adopting the AI's code suggestions that same day. In other words, developers almost instantly integrated AI into their daily coding routines. +
+ + +For ordinary people, this trend is even more significant: if professional programmers are relying heavily on AI to write code, **why can't those of us who don't know how to program communicate directly with AI to realize our ideas**? + +The goal of this course is to help you practice a new skill: building apps through natural language conversations. We will teach you how to communicate with AI using computer language and how to let AI turn the ideas in your head into real, usable products. + +
+ + + +
+ +## 2. To What Extent Can AI Help You? + +In this section, we only discuss one question: if you completely don't know how to write code, to what extent can today's AI help you? + +Roughly speaking, you can understand current LLM capabilities as: competent in developing **simple internal tools**, **data visualization dashboards**, and some **lightweight mini-games**. These are generally sufficient for making **tools for personal use** or validating requirements from a **product manager's perspective**. But to generate a **commercially mature product** with one click, it still typically requires manual, continuous polishing of **process design** and **details**. + +Next, let's take Snake as an example and see exactly what AI programming can achieve. + +### 2.1 Build a Snake Game in 60 Seconds + +First, please open the experimental site used in the course, [z.ai](https://chat.z.ai/). `z.ai` is an AI platform developed by Zhipu AI (one of China's leading LLM companies), powered by their proprietary GLM models. This platform includes various features, such as slideshow generation, poster design, and full-stack development. In this tutorial, we will focus on its full-stack development module. + +::: details 💡 What is the "programming right on the web" paradigm? + +In the past, developing a web app required: +- Installing programming environments (Node.js, Python, etc.) +- Configuring code editors +- Learning HTML/CSS/JavaScript +- Dealing with dependencies and errors + +Now, with AI coding platforms, you only need to: +- Open your browser and visit the site +- Describe your desired features in natural language +- Have AI instantly generate the code and let you preview the result live + +This "conversation as programming" paradigm changes coding from "writing instructions" to "describing requirements". You don't need to care about low-level technical details; just clearly state what you want. This is the new programming paradigm of the AI era—**Vibe Coding**. +::: + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/index-2026-01-07-18-25-03.png) + +Input our simple requirement and click the **Full-stack Development** button. You can watch the webpage being built in real time. Usually, it takes just the time to brew a coffee! + +``` +Help me create a Snake game: +1. Control snake movement with arrow keys +2. When it eats food, it gets longer and the score increases +3. Hitting walls or itself results in Game Over +4. Include Start and Restart buttons +5. The UI should be clean and elegant +``` + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/index-2026-01-07-18-34-03.png) + +Once generated, you will see a browsable webpage UI on the right. Scroll around or click the 🧭 button at the top to view it in full screen. + +> The buttons at the top from left to right are: Arrow button expands chat history, Pencil button to start a new chat, Refresh icon to rebuild the page, Compass icon to toggle fullscreen, Download button to download the project, <> button to view code, and Publish button to publish it. + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/index-2026-01-07-18-35-11.png) + +If you'd like to check the webpage's source code, click the code icon in the top right to view the entire codebase. + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image7.png) + +::: tip 🌐 Explore More AI Programming Tools + +Besides z.ai, we also recommend trying out these excellent AI programming platforms: + +| Tool | Link | Features | +|------|------|----------| +| **Google AI Studio** (Recommended)| [aistudio.google.com/apps](https://aistudio.google.com/apps) | Official tool from Google, powered by Gemini, great for rapid prototyping | +| **Figma Make** | [figma.com/make](https://www.figma.com/make) | Deeply integrated with design tools, ideal for interactive prototypes | +| **Coze** | [coze.com](https://www.coze.cn) | AI bot platform by ByteDance, zero-code visual building | +| **v0.dev** | [v0.dev](https://v0.dev) | AI generation for React components from Vercel | +| **Bolt.new** | [bolt.new](https://bolt.new) | AI full-stack development capable of generating deployed apps | +| **Lovable** | [lovable.dev](https://lovable.dev) | High-quality React app generation | +| **Replit Agent**| [replit.com](https://replit.com) | Online IDE integrated with AI | + +For more comparisons, view the appendix: [Comparison of 7 AI Programming Tools](../../stage-1/appendix-articles/example0-1/vibe-coding-tools-snake-game-tutorial.md) +::: + +### 2.2 What Conversational Programming Can and Cannot Do + +This section focuses on a specific question: When relying exclusively on conversational AI and writing no code at all, how far can you push a project? +In terms of experience, a fairly consistent conclusion is: It can help you complete a "small but complete" thing, but determining "how much is enough" still requires your personal decision on every detailed step. + +#### Excels at "Small and Clear" Apps + +From the Snake game example, you already saw a typical pattern: +As long as you can clearly describe the UI and interaction, AI can often piece together a fully functional, clickable webpage in just a few rounds of conversations. + +Such tasks often share a few characteristics: + +- Clear scope: one page, a simple internal tool, a small game mechanic. +- Visible results: you immediately see if it works as expected. +- Direct debugging: you can point out errors and ask for corrections easily. + +Within these boundaries, you can view the AI as a highly capable "junior assistant". + +**AI's success rate in handling small-scale tasks:** + + +#### Large Projects Require a "Process Perspective" + +Once it exceeds the small and clear scope, relying purely on conversational requests to build complex systems end-to-end will quickly hit ceilings. Large projects deal with backend databases, third-party services, authentication, permissions, edge cases, state management, etc. + +In these situations, the logical approach is to define a clear process flowchart and break it into segments to be handled individually. + +#### The Difference Between Generating and Validating + +Just because AI wrote it doesn't mean it's ready for a commercial launch! Always validate AI-generated code, especially in secure systems. + +::: warning ⚠️ Usage Guidelines +- **Prototypes/Tools/Demos**: Highly suitable for early stage builds iterations. +- **Large consumer-facing products**: Usually needs developers for architecture. +- **High-security systems**: Not suitable to deploy immediately. Needs stringent checks. +::: + +
+ + + +
+ +## 3. Hands-on: Your First AI Native Application + +Let's do some hands-on work. We'll add some native AI integration elements into our game. + +### 3.1 AI-Native Snake + +You can simply provide these prompts: + +> **💡 Example Prompt:** Build me a Snake game. +> +> ![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image12.png) + +> **💡 Example Prompt:** Build me a Snake game that supports: +> 1. Eating different words and placing them in a collection box. +> +> ![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image13.png) + +> **💡 Example Prompt:** Build a Snake game that supports: +> 1. I can eat distinct words, collected in a box. +> 2. When eating 8 words, the LLM generates a poem using them. +> 3. An image generation API is called right after the poem is composed. +> +> ![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image14.png) + +If you face any issues, just screenshot the error or tell the bot what's wrong and it will iterate the changes. + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image15.png) + +### 3.2 Add New Features to the Game + +After completing the basic functionality, we can try adding some new twists to our program! If you find the process of the snake eating words or characters a bit boring, you can have the snake eat words of different colors and change the snake's color accordingly. + +You can also add special effects to the "eating" process, or introduce magic words that trigger special effects—like increasing the snake's speed or size. Another idea is to have the model generate a poem and an image every time the snake eats a word, instead of waiting until it eats eight. + +If these feel challenging, you can ask the language model directly for help! It can provide creative suggestions to make your game more fun. Give it a try! + +``` +1. "Word Unlocks World" Mechanic +Every time the snake eats a word, the LLM performs a poetic association on that word (e.g., "tree" → "forest", "shade"), and the image model instantly generates a small artwork for that word. These images gradually piece together into a unique, player-created panorama, so players are "painting and writing poetry" with every playthrough. + +2. "Poetry Puzzle" Gameplay +Each word the snake eats triggers the LLM to generate a short verse, and the image model generates an illustration. These verses and images combine like puzzle pieces, forming an AI-collaborative poem and painting at the end of the round. + +3. "Magic Words" & "Story Branches" +Special "magic words" (e.g., "wind", "night", "dream") not only trigger the LLM to generate poetry but also change the mood or theme of the scene—transforming the generated image style to nighttime, stormy, or dreamlike atmospheres. +Branching story: The LLM gives a theme or riddle at the start (e.g., "autumn memories"). The player's word choices directly influence the story and poetry evolution, with the image model updating backgrounds and visuals in real time. + +4. "Real-time Interactive Generation" +After each word, the LLM generates a line of dialogue or description; NPCs in the game can "speak" to the player, or the environment can change accordingly. +The snake's appearance or obstacles in the game can visually change based on the words eaten, thanks to the image model. + +5. "Create & Share" +Players can save and share their AI-created poems and images at the end of a session, showing off their unique "AI collaboration." +Leaderboards for "Most Beautiful Poem + Art", "Most Creative Word Combination", etc., encourage replaying and creativity. + +6. "Sentence Snake" Challenge +Reverse mode: The LLM gives a line of poetry or a riddle, and the player must guide the snake to eat words in order to reconstruct the sentence. Eating the wrong word triggers funny or artistic consequences via the image generation model. + +7. "Themed Levels" & "Style Selection" +At the start of the game, the player chooses a theme (e.g., "fairy tale", "sci-fi", "Tang poetry"), and both the LLM and image model adjust word selection, poetry style, and visuals to match, making each run feel fresh. + +8. "Live Co-creation" +When a special word is eaten, the LLM can prompt the player to input a phrase or choose a style, then AI generates corresponding verses and illustrations, making it a true human-AI co-creation. + +9. "AI Easter Eggs & Achievements" +Certain word combinations are recognized by the LLM as special themes or inside jokes (e.g., "moon", "osmanthus", "riverbank"), triggering rare verses and illustrations that reward exploration. + +10. "A Growing Story" +As the snake grows, the LLM generates a continuous story-poem, and the image model creates a seamless scroll or panorama, so the player is simultaneously "writing, painting, and playing." +``` + +Additionally, we can also ask the LLM to generate project-level prompts for you directly. In the previous section, we only wrote the Snake game prompt ourselves. Now let's try having the LLM generate a prompt with an overall framework and implementation path (you can generate it directly with z.ai). + +If you want to learn how to write better prompts, check out the [Prompt Engineering Appendix](/zh-cn/appendix/8-artificial-intelligence/prompt-engineering). + +> I want AI to generate a web-based Snake game and need a more complete prompt to make the result more impressive and fun. Please generate the corresponding prompt. The current goal is: generate a Snake game that implements the function of eating different words to generate poetry, and should include an image generation module. + +z.ai's response will look like this: + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image56.png) + +We can use this prompt to regenerate the project in full-stack development mode: + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image57.png) + +![](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/image58.png) + +
+ + + +
+ +### 3.3 Try Making Other Mini-Games + +Beyond Snake, we can let our imagination run wild. + +Create anything we want to create, and even try to mess everything up! Then start over! + +``` +1. AI Art Gallery Platform + Description: An online gallery showcasing AI-generated artworks where users can upload, share, and comment on AI art. + Features: User account system, artwork upload and display, rating system, category browsing, AI generation tool integration. + Tech highlights: React/Vue frontend, Node.js backend, MongoDB database, AI API integration. + +2. Retro Game Archive + Description: A website paying tribute to classic games, featuring game history, gameplay guides, and playable retro games online. + Features: Game database, timeline display, online emulator, user reviews, game collection feature. + Tech highlights: Responsive design, WebGL/Canvas game implementation, RESTful API, user authentication. + +3. Sustainable Living Tracker + Description: A website helping users track and reduce their carbon footprint through eco-tips and community challenges. + Features: Personal carbon footprint calculator, goal setting, progress tracking, community challenges, eco knowledge base. + Tech highlights: Data visualization, mobile optimization, social features, push notifications. + +4. Virtual Kitchen Assistant + Description: An AI-based cooking guidance platform providing personalized recipe recommendations and step-by-step cooking instructions. + Features: Recipe database, ingredient recognition, personalized recommendations, cooking timer, nutrition analysis. + Tech highlights: Image recognition API, ML recommendation system, voice control, real-time video guidance. + +5. Underground Music Discovery Platform + Description: A music streaming platform focused on indie and emerging artists, offering a unique discovery experience. + Features: Music streaming, artist profiles, personalized recommendations, playlist creation, community reviews. + Tech highlights: Audio streaming, recommendation algorithms, social features, music visualization. + +6. Minimalist Task Management System + Description: A task management tool with zen aesthetics, focused on simple and efficient task organization. + Features: Task creation and categorization, priority setting, progress tracking, team collaboration, data analytics. + Tech highlights: Minimalist UI design, drag-and-drop, real-time sync, cross-platform compatibility. + +7. Sci-Fi Writing Workshop + Description: A platform providing creative tools and inspiration for sci-fi writers, including world-building aids and character development tools. + Features: Story structure tools, character profiles, world-building templates, writing statistics, community feedback. + Tech highlights: Rich text editor, data visualization, collaborative editing, AI-assisted creation. + +8. Personal Knowledge Graph + Description: A tool helping users build personal knowledge networks, visualizing and connecting various ideas and information. + Features: Node creation and connection, tagging system, search functionality, import/export tools, visual charts. + Tech highlights: Graph database, data visualization algorithms, Markdown support, cross-device sync. + +9. Virtual Botanical Garden + Description: An interactive plant encyclopedia where users can explore the plant world and create virtual gardens. + Features: Plant database, 3D plant models, growth simulation, gardening guides, community showcase. + Tech highlights: 3D rendering, seasonal change simulation, AR integration, plant recognition API. + +10. Programming Challenge Arena + Description: An online competition platform for programmers with coding challenges of various difficulty levels. + Features: Challenge problems, code editor, auto-evaluation, leaderboards, learning paths. + Tech highlights: Code sandbox environment, real-time evaluation system, algorithm visualization, social learning features. +``` + +And... if you enjoy playing games, let's try creating games together! + +``` +1. 3D Open World RPG + Description: A fantasy RPG with a vast open world, quests, and character progression. + Features: Day-night cycle, dynamic weather, skill trees, multiplayer co-op, crafting system. + Tech highlights: Three.js or Babylon.js for 3D rendering, server-side game logic, character customization, save system. + +2. First-Person Shooter (FPS) Arena + Description: A fast-paced multiplayer FPS with various game modes and maps. + Features: Team deathmatch, capture the flag, weapon customization, ranked matches. + Tech highlights: WebGL/Three.js for 3D graphics, multiplayer netcode, hit detection, voice chat. + +3. AI Chess and Multiplayer + Description: A full-featured chess platform with AI opponents and online matches. + Features: AI difficulty levels, endgame challenges, tournament mode, replay analysis. + Tech highlights: Chess logic library, WebSocket for real-time matches, ELO ranking system, anti-cheat. + +4. Mahjong Online Multiplayer + Description: A traditional Mahjong game with online multiplayer and scoring. + Features: Multiple rule sets, private rooms, ranking system, replay feature. + Tech highlights: Tile matching logic, real-time multiplayer, lobby system, score tracking. + +5. Turn-Based Strategy Game + Description: A tactical strategy game with grid-based combat and unit management. + Features: Campaign mode, skirmish, unit upgrades, fog of war, multiplayer battles. + Tech highlights: Grid movement system, AI decision-making, turn synchronization, save/load system. + +6. Time Trial Racing Game + Description: A 3D racing game focused on time trials and track records. + Features: Multiple tracks, car customization, ghost replays, leaderboards. + Tech highlights: 3D car physics, track editor, replay system, online leaderboards. + +7. Card Battle Game (Deck Building) + Description: A strategic card game where players build decks and battle opponents. + Features: Card collection, deck building, ranked matches, seasonal events. + Tech highlights: Card game logic, matchmaking system, AI opponents, card animations. + +8. Battle Royale (Top-Down 2D) + Description: A top-down 2D battle royale with shrinking play zones and loot mechanics. + Features: Solo and squad modes, weapon variety, in-match events, leaderboards. + Tech highlights: Real-time multiplayer, zone shrinking logic, loot generation system, matchmaking. + +9. Horror Survival Game (First-Person) + Description: A first-person horror game with resource management and escape mechanics. + Features: Atmospheric environments, puzzles, enemy AI, multiple endings. + Tech highlights: Dynamic lighting, sound design, enemy pathfinding, save system. + +10. Music Rhythm Game (3D) + Description: A 3D rhythm game where players hit notes to the beat of the music. + Features: Multiple difficulty levels, track editor, custom song support, leaderboards. + Tech highlights: Audio analysis, beat synchronization, 3D note tracks, input timing detection. +``` + +## 📚 Assignment + + + + +

+ In this section, you've followed the steps to experience the complete process from "conversational Snake generation" to "understanding AI-native game design thinking." The following assignments will help you turn this understanding into real skills. +

+ +
    +
  1. + Fully Reproduce the AI-Native Snake Game +
      +
    • At minimum, implement: the snake can move, eating "food" changes its length and score, and hitting walls or itself ends the game.
      • +
    • During reproduction, practice sending the error description + error message + key code snippets all at once to the AI, asking it to fix things in "beginner mode."
      • +
    +
    2. +
  2. + (Optional) Create 1 Original AI-Native Mini-Game or Demo +
      +
    • It can be any lightweight gameplay involving text, images, music, rhythm, etc., such as "eat words to write poems," "rhythm clicking," "generative runner," etc.
      • +
    • The focus isn't on flashy graphics, but on being able to clearly articulate: what specifically did AI help with here, and what "hard-to-do-manually or tedious" part did it solve.
      • +
    +
    3. +
+ +

+ That's the complete tutorial! You may need about 4 hours to finish all the content and build your own Snake game. Don't rush—explore, experiment, and enjoy the process. If you encounter concepts you don't quite understand along the way, we recommend checking the relevant sections in the appendix below. +

+ + +## Appendix + + +
Appendix Navigation
+
+ Here we've compiled some foundational concepts related to this chapter: if you encounter questions like "what is frontend?" or "what exactly does Vibe Coding mean?" during your learning, you can always come back here to look them up. +
+ + + Appendix 1: Do We Need Frontend Knowledge?
+ Understand where frontend fits in the overall application, and know which parts are "visible." + + + Appendix 2: What Exactly is Vibe Coding
+ Understand the core idea of "conversational development" and how to collaborate with AI. + + + + + Appendix 3: Model Context
+ Understand commonly heard but easily confused concepts like "context length." + + + Appendix 4: Instruction Following
+ Learn why models sometimes "don't understand" and how to write clearer instructions. + + +
+ Tip: You can press Ctrl/⌘+F to search for keywords, or copy confusing paragraphs to AI and ask it to explain again in a way "a complete beginner can understand." +
+ + +## [Appendix 1: Do We Need Frontend Knowledge?](#appendix-nav) + +::: tip 💡 One-line Summary +You don't need to write code, but understanding the basic concepts helps you describe requirements to AI more effectively. +::: + + + + + +
+ Everything users can see and click +
    +
  • Page titles, text, images
    • +
  • Buttons, input fields, dropdown menus
    • +
  • Game interfaces, animation effects
    • +
+
+ + + + + +
+ Data processing running on the server +
    +
  • User score storage
    • +
  • Login account verification
    • +
  • Level content distribution
    • +
+
+ + + + +### The Frontend Trio + +Browsers use three types of "code" to build pages: + + + +
+

Purpose: Defines what elements are on the page

+

Analogy: The structural blueprint of a house (where walls, doors, and windows go)

+ + 
<button>Click me</button>
+<h1>Title</h1>
+<img src="photo.png">
+ +
+ + +
+

Purpose: Controls how elements look

+

Analogy: The interior decoration of a house (colors, materials, layout)

+ + 
button {
+  background: blue;
+  color: white;
+  border-radius: 8px;
+}
+ +
+ + +
+

Purpose: Makes the page interactive

+

Analogy: The electrical switches of a house (responses after clicking)

+ + 
button.onclick = () => {
+  alert('You clicked me!')
+}
+ +
+ + + +### How Does Code Become a Page? + +When you open a webpage, the browser processes three types of code in order: + +**1. HTML — Defines the page structure** +The browser first parses HTML to understand what elements are on the page (headings, paragraphs, images, buttons, etc.) and their hierarchical relationships. + +**2. CSS — Applies styles** +Then the browser applies CSS rules to add styles to these elements: colors, sizes, positions, spacing, etc., making the page look beautiful. + +**3. JavaScript — Adds interactivity** +Finally, JavaScript code is executed to make the page "come alive": responding to clicks, submitting forms, playing animations, etc. + +**4. Page rendering** +The combined result of all three is the webpage you ultimately see. + +### Modern Frontend Frameworks: From HTML to React/Vue + +The HTML, CSS, and JavaScript introduced above are the "three essentials" of frontend development—they are the foundation of all webpages. But when pages become complex, developing directly with these three can be challenging: code becomes hard to maintain, there's lots of repetitive work, and data synchronization is troublesome. + +**Modern frontend frameworks** (like React, Vue, Angular) are built on top of HTML/CSS/JS to make development more efficient: + +**1. HTML/CSS/JS (Basic stage)** +Directly manipulating page elements, suitable for simple pages. But as code grows, all logic gets mixed together and becomes hard to maintain. + +**2. jQuery (Transitional stage)** +Simplified DOM operations, making code more concise. But you still need to manually manage page state and find corresponding elements to update when data changes. + +**3. React/Vue (Modern stage)** +Adopts component-based and state-driven design: +- **Component-based**: Break the page into independent, reusable modules (like buttons, cards, navigation bars) +- **State-driven**: When data changes, the framework automatically updates the corresponding UI without manual manipulation + +::: tip 💡 Simple Understanding +- **HTML/CSS/JS** = Basic materials (bricks, cement, steel) +- **React/Vue** = Building framework (provides standards and tools for constructing buildings) + +In the AI-assisted programming era, you don't need to deeply master every detail of frameworks. You just need to understand their basic concepts, and you can describe requirements in natural language to have AI generate code for you. +::: + +### In Vibe Coding + +**Core point: You don't need to write code, you just need to know how to describe.** + +After understanding frontend concepts, you can describe requirements to AI like this: + +> "Use React to make a leaderboard page, with a score list on the right side. Clicking a row shows player details below. The style should be clean and modern." + +If you want to dive deeper into frontend fundamentals like HTML, CSS, and JavaScript, check out the [Web Basics Appendix](/zh-cn/appendix/3-browser-and-frontend/javascript-deep-dive). To learn about the evolution of frontend technology, check out the [Frontend Evolution Appendix](/zh-cn/appendix/3-browser-and-frontend/frontend-frameworks). + +## [Appendix 2: What Exactly is Vibe Coding](#appendix-nav) + +> 💡 What is Vibe Coding? Computer scientist [Andrej Karpathy](https://karpathy.ai/) (one of the co-founders of OpenAI, former head of AI at Tesla) coined the term **vibe coding** in February 2025. This concept refers to a coding methodology that relies on LLMs, **allowing programmers to generate working code by providing natural language descriptions instead of manually writing code.** + +![1767350588191](../../../zh-cn/stage-0/0.2-ai-capabilities-through-games/images/1767350588191.png) + +Literally, Vibe Coding can be understood as a way of "developing by talking." The core change is: you no longer need to write code line by line, look up syntax, or debug yourself. Instead, you directly describe what you want in natural language, for example: + +"I need a login page with a phone number input field and a verification code input field." +"After successful login, redirect to the homepage and display the username in the top right corner." +"Give me a simple Snake game that can be controlled with keyboard arrow keys." + +The Large Language Model (LLM) will automatically translate these descriptions into real, runnable code and generate the corresponding pages, logic, and data structures. After you see the results, you can propose modifications in natural language, such as "make the button bigger," "change the background to dark," "record scores and display a leaderboard," and the AI will continue adjusting the implementation according to your requirements. + +In this mode, you don't need to learn a programming language first before writing code. Instead, you focus your main energy on: clearly stating what you want to do, judging "what's wrong" after seeing the results, and then proposing new modifications. AI handles turning these high-level ideas into concrete implementations, significantly reducing mechanical, repetitive coding work. + +You can click here to learn more about vibe coding: [https://www.ibm.com/think/topics/vibe-coding](https://www.ibm.com/think/topics/vibe-coding) + +You can click here to see more of Karpathy's shared content: [https://karpathy.bearblog.dev/blog/](https://karpathy.bearblog.dev/blog/) + +### How to Pretend You're a Vibe Coding Master + +In practice, during real vibe coding, we usually don't use many complex prompts. Perhaps we need a specific and moderately complex prompt for the entire program at the beginning, but after that, at each step, you may only need prompts like these: + +``` +"There's a bug in the code, please fix it." +"I don't want partial code, give me the complete modified code." +"Your code still has problems." +"Please modify again and give me the complete corrected code." +"It was working before, why isn't it working now?" +"Did you not understand what I meant? Don't change my original code." +"Don't add any debugging features." +"Don't do things I didn't ask you to do." +"Where is the feature I asked you to implement?" +"Can you not understand what I'm saying?" +"I only want one function." +"I told you to refer to my previous code." +"Please don't add unnecessary comments." +"Please don't modify the basic logic of my original code." +"Help me modify the code." +"Modify based on my code..." +"Don't change my variable names!!!" +"Don't change the original function names!" +"Don't mess with my variables." +"Don't add extra features." +"Don't just generate a skeleton, generate the complete code." +``` + +This may sound a bit exaggerated, but in reality, these are the prompts we might use in daily work. Due to the **context length limitations** of large language models, or sometimes because their **instruction following ability** isn't very strong, models may forget content discussed earlier in the conversation. In vibe coding, we tend to use models with long context and strong instruction following ability. We can judge whether a model is good through rankings or metrics of these two aspects. + +Alternatively, due to the style of training datasets, large models tend to respond in the style of their training data. For example, some speak very seriously, some like to add lots of embellishments, and some models like to add lots of comments or unnecessary modules to code. + +## [Appendix 3: Model Context](#appendix-nav) + +Model context can be understood as AI's short-term memory. It refers to all the text content that the model can "see" and "remember" during a single conversation or task, including your previous questions, system-provided instructions, relevant materials, etc. + +It is precisely because of context that AI can understand you're continuing from previous content, enabling round after round of coherent, natural conversation. Without context, every sentence you say would appear to the model as a completely new question—it wouldn't know what you said before, and there would be no way to continue a conversation. + +Each model has its own effective context length (context window). This length is usually measured in tokens (which can be roughly understood as units of "word fragments"), and most mainstream models currently range from 32k to 128k tokens. The longer the context, the more content the model can "read" at once, for example: + +- Reading an entire lengthy paper or report in one go +- Referencing multiple materials and cases in the same conversation +- Having the model remember conclusions from complex discussions several rounds ago + +When your input approaches or exceeds the model's context limit, some common phenomena often appear: + +- The model starts forgetting details or key information from earlier in the long text +- As the conversation progresses, the topic gradually drifts from the original goal +- Across different Q&As about the same material, the referenced content becomes inconsistent + +These phenomena don't mean the model suddenly "got dumber"—they are natural results of the context capacity being used up or nearly used up. + +In practical use, we want the context to be as long as possible, while also being aware that: + +- The longer the context, the more computing resources it consumes +- The corresponding API costs (fees) also increase accordingly + +Therefore, when designing AI applications, you need to balance letting the model see enough information with controlling costs and improving efficiency. For example: + +- Distill information that truly needs long-term retention before feeding it to the model +- Avoid stuffing detail information that's no longer needed into the context repeatedly +- Use external knowledge bases and similar approaches to hand "long-term memory" to the system rather than forcing it into the model's context + +## [Appendix 4: Instruction Following](#appendix-nav) + +Instruction following refers to: after the model understands your instructions, whether it can accurately and completely execute according to your requirements. This includes not only answering questions, but also completing tasks in specified formats, styles, and steps. + +For example, the following are all instructions with clear requirements for the model: + +- Summarize this article into three key points +- Write a reply email in a formal, polite tone +- Translate this word into English and create an example sentence for each +- Extract the author, time, and main events from the article + +A model with strong instruction following ability typically has these characteristics: + +- Outputs content in the required quantity + For example, if asked to summarize three key points, it won't give five. +- Covers all specified elements + For example, if asked to extract author, time, and events, it won't omit any of them. +- Follows the specified format and tone + For example, if asked to use a formal tone, it won't output overly colloquial responses. +- Doesn't make unnecessary additional extensions + For example, if only asked to translate and create sentences, it won't output a large paragraph of unrelated explanations. + +In practical applications, strong instruction following ability is very important for these reasons: + +- Improved stability: The same instruction produces more consistent output structure and behavior patterns across different times and multiple runs, less likely to go off-script +- Improved reproducibility: When you configure a prompt into a product or workflow, you can predict roughly how the model will respond, making testing and iteration easier +- Easier system integration: When model output conforms to expected formats, it's easier to automatically interface with backend programs, workflows, or other tools + +Therefore, when selecting and evaluating a large language model, in addition to focusing on whether it's smart and has broad knowledge coverage, you also need to pay special attention to its instruction following ability. For industrial-grade applications, being able to stably and accurately execute instructions is often more important than occasionally giving a stunning answer. diff --git a/docs/en/stage-0/index.md b/docs/en/stage-0/index.md new file mode 100644 index 0000000..b6158ea --- /dev/null +++ b/docs/en/stage-0/index.md @@ -0,0 +1,129 @@ +# Build Your First AI Product + +Welcome to the **Build Your First AI Product** stage! This is the starting point of the Easy-Vibe tutorial, specifically designed for learners with zero programming background. + +## What You Will Learn + +In this stage, you will start from zero and master the Vibe Coding workflow, becoming a super individual capable of independent product design. + +### Getting Started + +Suitable for learners with product, operations, and non-technical backgrounds. Understand AI programming logic through games and build learning confidence: + + + + + + +### Product Prototype Practice + +Master the Vibe Coding workflow, learn to deconstruct requirements, and independently complete high-fidelity Web application prototypes: + + + + + + + + + +### Appendix: Business Thinking + +**Why needed**: When you need to enhance product thinking and understand industry application scenarios, this content can help you establish a more comprehensive product perspective. + +**When to watch**: +- Before starting to build a prototype, understand product thinking first to help you plan and design better. +- When you have a product idea but are unsure of the direction, refer to industry scenario cases. +- After completing the project, use product thinking to review and optimize your work. + + + + + + + +### Appendix: Technical Solutions + +**Why needed**: When you encounter technical problems during development or want to know better tools, these technical appendices provide ready-to-use solutions. + +**When to watch**: +- When you encounter an error and don't know how to solve it, check common errors and solutions. +- When you want to compare different AI programming tools, refer to platform measurement comparisons. +- When you want to learn more advanced development skills, check agent development cases. + + + + + + + +## Suitable for + +- Product managers and operations personnel with zero foundation +- Entrepreneurs who want to quickly validate ideas +- Non-technical individuals interested in AI programming +- Designers who hope to improve their prototype design capabilities + +## How to Learn? + +It is suggested to follow this order: + +``` +Play games to build confidence → Follow the tutorial to make a prototype → Add AI functions to the prototype → Independently complete a full project +``` + +Don't read everything at once; learning while doing is most effective. When you encounter problems, remember to check the appendix for solutions. + +Start now, select the first section in the left navigation! diff --git a/docs/en/stage-1/1.1-introduction-to-ai-ide/index.md b/docs/en/stage-1/1.1-introduction-to-ai-ide/index.md new file mode 100644 index 0000000..0059bf5 --- /dev/null +++ b/docs/en/stage-1/1.1-introduction-to-ai-ide/index.md @@ -0,0 +1,361 @@ + +# Beginner Level 2: Learn AI Programming Tools + +## Chapter Overview + + + + + +Previously, we experienced AI programming on z.ai, but the web version has many limitations — you **can't save your work anytime**, it's **hard to manage files**, and you **can't handle complex projects**. This chapter helps you move your development environment to your own computer so you can **truly build things independently**. + +We'll first clarify **what the difference is between an IDE and an AI IDE**, and why the latter can **double your efficiency**. Then we'll **walk you through step by step** using Trae to build a Snake game locally, covering the **complete workflow** from installation to running. Finally, we'll share some **practical tips** for communicating with AI so you can avoid common pitfalls. + +After completing this chapter, you'll have **mastered a development workflow similar to that of professional programmers**. + +::: tip 💡 Advanced Tip +If you have some programming experience and want to use more powerful tools early on, you can refer to [Modern CLI Coding Tools](../../stage-2/backend/2.6-modern-cli/extra7/) to develop using the command line. +::: + + + +
+ + + +
+ +## 1. What Environment and Tools Do You Need to Write Code + +### 1.1 Mindset Shift: When in Doubt, Ask AI First + +Before we introduce the various environments and tools, here's an important reminder: you need to **change your thinking habits**. + +In traditional programming learning, if you need to install Python, configure Conda, or fix an npm installation failure, you'd typically open a search engine, find a tutorial, and follow the steps one by one. If you hit an error along the way, you'd search for the error message and try again repeatedly. + +Wrong! ❌ + +In the AI era, especially when using an AI IDE, remember one core principle: **For any task, you can ask AI first, or even let it do it for you.** + +- **Don't know how to set up your environment?** Just ask AI in the sidebar: "I want to write Python. Please check if Python is installed, and if not, install it for me." +- **Network stuck?** If installing dependencies keeps spinning or throwing errors, just throw the error to AI: "The download failed. Is it a network issue? Can you help me switch to a different mirror source?" +- **Can't remember commands?** No need to memorize Git or Conda commands. Just tell AI: "Help me create a new virtual environment called demo." + +### 1.2 Why You Need an Environment and Tools + +Going from "trying to write a few lines of code" to "building a long-term maintainable project" requires completely different environments and tools. + +In theory, you could write code with the system's built-in Notepad, but problems quickly arise: + +- **All code is plain black text** — keywords, strings, and comments are all mixed together, making it hard to see the structure at a glance +- **No smart suggestions** — you have to type every word completely by hand, and a single typo means repeatedly checking your code +- **Files become chaotic** — switching back and forth between dozens of files, often unable to find the line you need to edit +- **Debugging is guesswork** — when the program crashes, you don't know what went wrong and can only add print statements line by line + +That's why you need an IDE (Integrated Development Environment). It displays code in different colors, provides auto-suggestions as you type, organizes files by project, and lets you trace errors step by step — making development more efficient and less error-prone. + +## 2. What Is an IDE, and Why Do You Need One + +::: info Pre-reading Tip +If you're not yet familiar with what an IDE is or what each interface element does, we recommend reading [IDE Basics](/zh-cn/appendix/2-development-tools/ide-basics) first to learn the basic concepts and common features. +::: + +In the early days of programming, all we needed was a simple text editor and a language processor. But as projects grew more complex, developers urgently needed a tool that could efficiently manage files, support syntax highlighting, and enable debugging — and thus the Integrated Development Environment (IDE) was born. + +You can think of an IDE as a program specifically designed to "edit, manage, run, and debug" code. Early IDEs looked very "primitive" and were operated almost entirely through the keyboard. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image1.png)![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image2.png) + +Terminal Interface — Image source: https://en.wikipedia.org/wiki/File:Emacs-screenshot.png + +Well-known and mature "built-in IDEs" like `Vim` are commonly used for remote server operations. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image3.png) + +For greater efficiency, we need modern IDEs that support mouse interaction, typically including: + +- **Source Code Editor**: Syntax highlighting, auto-completion. +- **Build and Run Tools**: Built-in compiler/interpreter. +- **Debugger**: Breakpoint debugging, variable inspection. + +Modern IDEs often also include built-in tools like Git. The most popular is Microsoft's **[Visual Studio Code (VS Code)](https://code.visualstudio.com/)**, which is lightweight and extensible. While there are also professional IDEs like the JetBrains suite, VS Code is the most beginner-friendly. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image4.png) + +VS Code's core philosophy is "everything is a plugin." Through its plugin system, it supports various languages — install the Python plugin and it becomes a Python IDE, install the C++ plugin and it becomes a C++ IDE. Without plugins, it's just an advanced text editor. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image5.png) + +You can even use it to edit Markdown documents. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image6.png) + +In short, an IDE is a set of tools that helps developers write code and run programs efficiently. + +For more detailed explanations, check out the [Virtual IDE Visualization section in the Appendix](/zh-cn/appendix/2-development-tools/ide-basics). + +## 3. How Is an AI IDE Different from a Regular IDE + +A regular IDE (like the original VS Code) is essentially a "toolbox": +You can open projects, write code, run and debug, and install plugins — but the prerequisite is that you need to know what to do and how to do it yourself: + +- When there's an error, you read the message yourself and figure out which line has the problem; +- When you want to add a new page or API endpoint, you find the right file and write the code yourself; +- When you want to configure the environment or build the project, you look up the documentation and follow the steps yourself. + +But in an AI IDE, you can directly use a large language model to help you code and modify files: + +- Just say "make a login page," and it generates the basic code structure first; +- Throw the error message and related code at it, and let it analyze the cause and suggest fixes; +- After you confirm, let it automatically create files, batch-edit code, and handle cross-file grunt work. + +For example, you can select a piece of code and ask it to "refactor this" or "add comments." You can also ask in the sidebar "How is this project designed?" and specify the reference scope using `@filename` or `@entire project`, completing the tedious operations of creating files, writing code, and running with a single sentence. + +In the latest version of VS Code, a large language model assistant is already built in. You can have conversations with the model about the entire codebase, a specific file, or even a specific function. You can also use it like the auto-coding tools you used on the web — send your requirements as prompts to the built-in coding Agent, and let it automatically implement the features you need, create files, modify code, configure environments, and more. + +You can download and install VS Code, click the sidebar entry in the top-right corner, and open the AI feature area to experience these capabilities. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image7.png) + +However, VS Code is not the IDE with the strongest AI capabilities. For scenarios that require heavy AI-assisted coding, we often want to use "smarter, more efficient" tools — a good AI IDE can significantly save time on writing code and fixing bugs. Below we'll introduce several popular AI IDEs. You can choose any AI IDE based on your personal preference. + +Since VS Code is open source (anyone can download the source code and compile it themselves), the vast majority of AI IDEs on the market today are built on top of VS Code. So you don't need to worry about "learning many different IDEs" — **as long as you're familiar with the basics of VS Code**, migrating to these AI IDEs doesn't require starting from scratch. + +Generally speaking, the differences between AI IDEs mainly come down to four aspects: pricing; available model types (some advanced models may be restricted in certain regions); Agent capabilities (how smart and capable it is at assisting with coding); and speed and performance. You can choose based on your own testing results — the best tool is the one that works best for you. + +> Typical AI IDEs generally have the following core capabilities: +> +> - Smart Code Generation and Completion: In traditional IDEs, we typically type a few characters to auto-complete variable or function names. In modern AI IDEs, you can write a few lines of pseudocode or simply describe your requirements, and the IDE will auto-complete the full logic, or even generate large blocks of code based on instructions. +> - Code Understanding and Q&A: The IDE can understand and answer questions about a specific piece of code, a file, or even the entire project directory structure. +> - Code Refactoring and Optimization: The IDE can rewrite or optimize the implementation logic of specified code snippets based on your intent. +> - Automatic Test Generation: The IDE can automatically generate test code for different functions and modules, making it easy to perform targeted testing. +> - Agent-style Task Execution: Smart Agents can automatically generate, build, install, run, and modify code, partially replacing the work of junior software engineers in many tasks. + +::: details Antigravity + +### [Antigravity](https://antigravity.google/) + +Antigravity is a brand-new AI IDE released by Google in November 2025 alongside Gemini 3, adopting an "Agent-First" development model. Unlike traditional AI-assisted coding, Antigravity makes the AI agent the "active executor," capable of directly operating the editor, terminal, browser, and other tools, taking on more "execution," "planning," and "verification" work. Developers only need to express high-level intent, and the agent will automatically break down tasks, create plans, execute code, run tests, and generate results. It supports multi-model switching, including Gemini 3 Pro, Claude Sonnet 4.5, and more. It's currently available as a public preview, supporting Windows, macOS, and Linux. +::: + +::: details Trae + +### [Trae](https://www.trae.ai/) + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image8.png) + +Trae is an AI programming assistant developed by ByteDance that supports over 100 programming languages and can be integrated into mainstream IDEs. Its features include: generating code from natural language, automatic debugging, and converting design mockups into React/Vue components. After its August 2025 update, Trae added smart dependency imports, rename suggestions, task checklist management, and more. SOLO mode also began supporting backend code generation and technical architecture document editing. +::: + +::: details Cursor + +### [Cursor](https://cursor.com/) + +Cursor is an AI code editor developed by Anysphere, built on a customized VS Code, with optimizations focused on large-scale codebases and multi-file collaboration scenarios. It supports models like GPT-4o and Claude 3.7. The Claude Max mode introduced in 2025 can handle projects with millions of lines of code. The Pro version removed request limits, making it ideal for complex enterprise projects. + +Currently, Cursor is arguably one of the best AI IDEs with a graphical interface in terms of overall experience, with a large user base and frequent feature updates. Its biggest drawback is the higher price — the Pro version costs about $20 per month. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image9.png) +::: + +::: details Qoder + +### [Qoder](https://qoder.com/) + +Qoder is an AI IDE from Alibaba that emphasizes "transparent collaboration" and "enhanced context engineering capabilities." It supports breaking tasks into multiple steps through Action Flow and tracks AI execution in real time. It also supports multi-model dynamic routing and task state machine management, making it ideal for architecture governance in medium-to-large projects and "reverse engineering" analysis of legacy systems. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image10.png) +::: + +::: details CodeBuddy + +### [CodeBuddy](https://www.codebuddy.com/) + +CodeBuddy is an AI programming tool from Tencent Cloud that emphasizes Chinese language command support and enterprise-grade compliance capabilities. It offers code completion, batch code review, and multi-model switching. Its Craft agent can perform multi-file code generation and API integration. The enterprise version supports private deployment and has passed Level 3 security certification, making it suitable for industries with high data security requirements such as finance and healthcare. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image11.png) +::: + +::: details VS Code + Cline + +### VS Code + [Cline](https://cline.bot/) + +Cline is an AI programming Agent plugin for VS Code (Visual Studio Code) that can flexibly switch between different large models by configuring different API endpoints. Cline supports multimodal input, MCP tool extensions, and cost monitoring, with all operations requiring user confirmation before execution. It's ideal for quickly validating ideas or integrating with existing development workflows. Basic features are free, and the enterprise version supports deploying models in private environments. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image13.png) + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image14.png) +::: + +::: details Kiro + +### [Kiro](https://kiro.dev/) + +Kiro is an AI programming IDE from AWS (Amazon Web Services), deeply integrated with Amazon Bedrock and the AWS cloud service ecosystem. It supports multiple large models including Claude and Nova, making it particularly suitable for development scenarios that require tight integration with AWS cloud services. Kiro provides smart code generation, automated testing, and seamless integration with AWS resources (such as Lambda, S3, DynamoDB), offering unique advantages for cloud-native application development. + +> **Note**: If you want to use Anthropic Claude models, you'll need to use Cursor, Kiro, or Antigravity as your IDE. These IDEs have official partnerships or deep integrations with Anthropic, providing a more stable and complete Claude model experience. +::: + +
+ + + +
+ +## 4. Hands-on: Build a Snake Game Locally with an AI IDE + +The previous sections were mainly about "concepts" and "differences." In this section, we'll turn abstract concepts into concrete actions through a complete hands-on exercise: **Create a new empty folder -> Open it with an AI IDE -> Chat in the sidebar and have it build a Snake game from scratch using React.** Here we'll use Trae as our example, so first we need to install it and understand what Trae is. + +::: tip 💡 Quick Tip: Seamless Transition from Web to Local +If you've previously developed projects on z.ai or other web-based AI programming platforms, you can download the code directly to your local machine and open it with an AI IDE to continue development. This way you can keep your previous work while enjoying the more powerful AI assistance of a local IDE. + +The steps are simple: +1. Click the download button on platforms like z.ai to save the project locally +2. Unzip and open the folder with an AI IDE like Trae/Cursor +3. Continue chatting with AI in the sidebar to iterate and improve your project +::: + +### 4.1 Preparation: Install and Learn About Trae + +#### 4.1.1 What Is Trae + +Trae's full name can be understood as "The Real AI Engineer." It's an adaptive AI Integrated Development Environment (IDE) developed by ByteDance. It's built on top of the popular VS Code, which means if you're already familiar with VS Code, you'll find Trae's interface layout and basic operations very familiar and comfortable. + +Trae's core goal is to be a developer's "smart programming partner." Through deep AI integration, it can automatically handle a large amount of repetitive work, providing you with a more intuitive and efficient development experience. It's not just a "code completion tool" — it aims to assist throughout the entire development workflow, from creating projects, writing code, debugging, testing, to deployment. + +#### 4.1.2 Installing Trae + +Trae comes in an international version and a China version. The international version requires access to overseas networks but lets you use the latest overseas models like GPT-5. The China version primarily supports the latest domestic large models such as GLM, Qwen, Kimi, etc. + +International version download: https://www.trae.ai/ +China version download: https://www.trae.cn/ + +##### Trae Pricing and Usage Options + +::: info 💡 Version Selection Tips +- If you're primarily using it in China, we recommend choosing the China version for more stable network access and support for domestic large models +- If you need to use overseas models like GPT-5 and your network conditions allow it, you can choose the international version +- If you already have a third-party model API Key, connecting third-party models gives you flexible cost control +::: + +> 💡 **Currently recommended: Use OpenRouter free models for testing** +> +> As of the time this tutorial was written (2026-02-12), you can still try StepFun's models for free. See section 4.2 below for how to connect the model `stepfun/step-3.5-flash:free`. + +Regarding Trae's costs and usage options, here are several choices: + +- **China Version (Recommended)**: Basic usage is free, but due to high user volume, you may need to wait in a queue. +- **International Version**: Subscription costs about $3 per month, giving access to overseas models like GPT-5, but requires overseas network access. +- **Third-party Model Integration**: If you already have a Token API from a domestic large model provider (such as DeepSeek, Tongyi Qianwen, Kimi, etc.), you can connect these APIs through Trae's third-party model configuration. Major cloud service providers (such as Alibaba Cloud, Tencent Cloud, Baidu Cloud, etc.) typically offer Coding Plan subscriptions that let you use their large model APIs at more favorable prices. This way you can freely choose your preferred model while controlling costs. + +We recommend beginners start with the free China version. If you encounter queuing issues or need more stable service, consider connecting a third-party model and purchasing the corresponding cloud provider's Coding Plan. + +#### 4.1.3 Trae Interface Overview + +In terms of interface design, Trae is very similar to the VS Code we use daily: the same classic three-column layout with a file explorer on the left, an editing area in the center, and an extension panel on the right. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image17.png) + +The sidebar on the right is the Copilot interaction window, which can also be thought of as the Agent window. If you can't see it right away, click the sidebar icon in the top-right corner of Trae to open it. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image18.png) + +After opening the sidebar, you'll see a `Builder` option — this is the Agent mode. Simply put, it's like a "local version" of z.ai that can operate your local environment, install runtime environments, open web pages, and more. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image19.png) + +After clicking "Builder," you'll see "Chat" mode and "Builder with MCP" mode: + +- **Chat Mode**: Primarily used for chatting about the code in your current folder, or as a general chat model. (You can open a folder through the "File" menu in the top-left corner and edit within that folder. In this case, any files Builder creates or modifies will only happen inside this folder.) +- **Builder with MCP Mode**: Provides the Agent with more available tools (such as connecting the language model with other software, querying weather, etc.). You can simply understand it as: MCP makes it easier for the language model to call various external tools. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image20.png) + +In the area below, you'll also see model selection options — click to change the current large model. In the China version, you can choose domestic models like Kimi k2 or GLM. If you're using the international version of Trae, you can also select overseas models like ChatGPT or Claude. However, since domestic large models are developing very rapidly, Kimi, Qwen, GLM, and others already offer experiences close to Claude 3.5 or 3.7 in many tasks, which is more than sufficient for daily development. There's no strict requirement to use the international or China version here. + +**Note that we don't recommend using Auto mode (automatic model selection). For the international version, we recommend using Gemini or GPT models. For the China version, we recommend trying domestic models like Kimi k2, Minimax, or GLM.** Different models suit different use cases — there's no dogmatic rule about which is better. When you hit a wall with one model, try switching to another. Through multiple tests, you'll find the best results for your own workflow. + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/image21.png) + +That's a brief introduction to Trae. Next, let's revisit what we did previously on z.ai and try doing the same thing in Trae. + +### 4.2 Step 1: Create an Empty Folder and Open It with an AI IDE + +Before getting started, we first need to prepare a clean project working directory. +For this section's example, you can create a new empty folder named `snake-game-react` on your local machine. + +Then, open your installed AI IDE, select "Open Folder" on the startup screen, and import the empty folder as the project root directory. You can also drag the folder directly into the IDE window to open it. At this point, the file explorer on the left won't show any code files, indicating that we're starting from a completely blank project state. + +::: details 📚 Optional: Connect a Cloud Service Provider's API or Coding Plan + +This section introduces how to connect a cloud service provider's API or Coding Plan for more stable and frequent model calls. Screenshots of the Trae integration are provided at the end. + +**What Is a Coding Plan** + +A Coding Plan is a subscription offered by major cloud service providers. After purchasing, you can **use the provider's large model API without limits or at high frequency** for a certain period. Compared to per-token billing, a Coding Plan is more like a "monthly package" — you pay a fixed fee and can use it freely without worrying about per-call charges. + +**Why Purchase a Coding Plan** + +You might ask: since you can call large models directly via API, why buy a Coding Plan? The main reason is: **unlimited usage**. The core advantage of a Coding Plan is that you can call the large model anytime, as frequently as you want, without worrying about costs exploding or constantly checking billing statements. + +**Recommended Domestic Cloud Service Coding Plans** + +Here are recommended Coding Plan options from major domestic cloud service providers: + +- Zhipu AI (BigModel Plan): https://bigmodel.cn/glm-coding +- Volcengine (ByteDance Cloud AI Plan): https://www.volcengine.com/activity/codingplan + +> 💡 **You can also directly connect a large model API** +> Besides Coding Plans, you can also directly connect various model APIs through Add Model. You can refer to the method below for connecting the OpenRouter StepFun free API to integrate it with Trae. Testing shows it meets basic programming needs. +> If you need to top up, we suggest starting with a small amount (e.g., 10 RMB) to see how long it lasts, such as with cost-effective models like DeepSeek. + +**How to Connect a Coding Plan** + +Connecting a Coding Plan is very simple and takes just a few minutes: + +1. Visit your chosen cloud service provider's website (e.g., Zhipu AI: https://bigmodel.cn/glm-coding, Volcengine: https://www.volcengine.com/activity/codingplan) +2. Register an account and log in +3. Find the "Pricing" or "Coding Plan" page +4. Choose a plan that suits you and complete the payment +5. After payment, you'll receive an API Key or Plan ID + +::: tip 🎯 Custom Model Recommendations + +When connecting custom models in Trae, we **recommend using the OpenRouter approach by default**. OpenRouter provides a unified API interface for conveniently connecting to multiple large language models. + +**As of February 12, 2026, you can still use StepFun's free API:** + +- **`stepfun/step-3.5-flash:free`**: A free model from StepFun that can be directly connected in Trae. + +**Other free models:** + +- **`openrouter/free`**: A model option that uses free LLM APIs by default. You can use it directly in Trae's Custom Model integration (just enter the model ID), experiencing AI programming features without any cost. + +These free options are great for beginners. Before committing to production use, you can familiarize yourself with the AI IDE workflow through these free options. + +**Optional: Connect a Large Model API (Using DeepSeek as an Example)** + +1. Visit the DeepSeek platform: https://platform.deepseek.com/usage +2. Register an account and log in +3. Purchase a 10 RMB token package on the top-up page +4. After topping up, create and copy an API Key on the API Keys page +5. In Trae, click **"Add Model"**, find DeepSeek, select the corresponding model, and enter the API Key to start using it + +Through the interface below, you can successfully add a model (note: after selecting the model option, **make sure to scroll all the way to the bottom** — there's a "Custom Model" option. Click it to enter a model ID, where you can type the recommended model IDs like `stepfun/step-3.5-flash:free`. Also click "Get Key" below to visit the official website and obtain the corresponding API Key.) + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/index-2026-02-12-14-14-51.png) + +![](../../../zh-cn/stage-1/1.1-introduction-to-ai-ide/images/index-2026-02-12-14-15-29.png) +::: diff --git a/docs/en/stage-1/1.3-integrating-ai-capabilities/index.md b/docs/en/stage-1/1.3-integrating-ai-capabilities/index.md new file mode 100644 index 0000000..6f5982c --- /dev/null +++ b/docs/en/stage-1/1.3-integrating-ai-capabilities/index.md @@ -0,0 +1,287 @@ +--- +title: 'Adding AI Capabilities to Your Prototype - Integrating Text and Image APIs' +description: 'Integrate real AI capabilities into your existing web prototype: understand the core concepts of APIs, learn how to find API Keys and official examples; hands-on integration of DeepSeek text model and various image generation services (SiliconFlow Qwen-Image, Recraft, Seedream), and master common model selection methods.' +--- + + + +# Beginner Level 4: Injecting AI Capabilities into Your Prototype + +## Chapter Introduction + + + +In the previous chapters, we completed the entire process from **finding a great idea** to **building a product prototype**. But the current prototype is still just a "shell" — clicking buttons won't actually generate content, and all the data on the page is hardcoded. + +Remember what we emphasized in the first chapter? **We want to build "products people are willing to pay for," not "prototypes that just look good."** Real value comes from a product that can **solve real problems**, and to achieve that, the prototype must be able to **actually run**. + +This chapter will bring your prototype **"to life"**: we'll integrate **real AI capabilities**, starting from obtaining an API Key, reading official documentation, and having the AI IDE help you integrate the interface into your code. Using **DeepSeek's text model** as an example, you'll learn how to make your application **actually call a large language model to generate content**; if you're interested, you can also **optionally integrate image generation**. + +After completing this chapter, your prototype will **no longer be a static demo**, but rather **an application that can call real AI capabilities and solve real problems**. + + + +
+ + + +
+ +# 1. API Fundamentals + +As mentioned earlier, our goal is to "integrate AI capabilities" so that the prototype is no longer a static demo but a tool that can call real AI services. The key to achieving this lies in understanding and using APIs (Application Programming Interfaces). + +API is an important abstraction concept in computer science. Simply put: **you send a request in the format the other party requires, and they send back a result in the same format**. + +- **What you send out**: Usually includes a "key (API Key)" and "what you want to generate" +- **What they send back**: If successful, you get the result; if it fails, they tell you why (e.g., "invalid key," "insufficient balance," "incorrect parameters") + +Specifically, you need to master the following core elements: + +1. **API Key**: Your "pass" and also your "wallet key." Anyone who gets it can make API calls on your behalf and incur charges. +2. **Endpoint**: The specific path for the API request, telling the server which function you want to access. The full request URL is typically composed of "Base URL + Endpoint path." For example: + - Text generation: Base URL (`https://api.service.com`) + Endpoint (`/v1/chat/completions`) = Full URL `https://api.service.com/v1/chat/completions` + - Image generation: Base URL (`https://api.service.com`) + Endpoint (`/v1/images/generations`) = Full URL `https://api.service.com/v1/images/generations` +3. **Call/Request**: The process of sending a task to the AI service and getting results back +4. **Request Content**: The specific content you send to the AI, such as the topic you want the AI to write about, the description of the image to generate, etc. +5. **Response**: The content the AI returns after processing, such as the generated article, image, etc. +6. **Error Handling**: Knowing how to troubleshoot when problems occur (such as incorrect API Key, too many requests, etc.) + +::: info ℹ️ What is an API +For a more in-depth explanation of APIs, see the appendix: [Introduction to APIs](/zh-cn/appendix/4-server-and-backend/api-intro). + +::: warning 🔐 **API Security Notes** +The API Key is your "pass" for requesting AI services — it's a secret string used for authentication and billing. + +Since the API Key is directly linked to your account and charges, be sure to: + +- **Never share it** in group chats, screenshots uploaded online, or public forums +- **Never hardcode it** into your code and commit it to a Git repository (especially public repositories) +- If you suspect your Key has been leaked, **replace it with a new Key immediately** + +In the content below, we will **paste the API KEY directly into the AI IDE for operations**. **Don't do this in real projects!!** Since we're just practicing, it's fine for now. (Once you're more experienced, you can have the AI generate a configuration file and simply put the API KEY in the config file.) +::: + +
+ + + +
+ +# 2. Integrating the Text Generation API: DeepSeek + +Although APIs involve these technical concepts, the actual operation during the prototyping phase can be very simple and efficient. The core approach is: + +> **Find the official example, get the API Key, and have the AI IDE help you wire it to a button.** + +Once you've grasped these concepts, you'll find that whether you're integrating a text model or an image model, the underlying process is the same: when the user clicks a button, the frontend organizes the input and sends a request; after the API returns a result, it displays the result on the page. Let's verify this through hands-on practice. + +In `1.2 Building Your Prototype`, you already created an interactive prototype. What we need to do next is turn the "AI-like features" in the prototype into real, working capabilities: **when the user clicks a button, the prototype sends a request to an external AI service and displays the returned text.** + +::: info ℹ️ Further Reading on Principles +If you want to learn more about the underlying principles, check out the appendix: [Introduction to Large Language Models (LLM)](/zh-cn/appendix/8-artificial-intelligence/llm-principles). +::: details Learn More: What is DeepSeek? + +**Hangzhou DeepSeek Artificial Intelligence Basic Technology Research Co., Ltd.**, operating under the brand name DeepSeek, is a **Chinese artificial intelligence (AI) company that develops large language models (LLMs)**. DeepSeek is headquartered in Hangzhou, Zhejiang, and is owned and funded by the Chinese hedge fund High-Flyer. DeepSeek was founded in July 2023 by Liang Wenfeng, co-founder of High-Flyer, who also serves as CEO of both companies. The company launched its eponymous chatbot and its DeepSeek-R1 model in January 2025. + +Let's look at how DeepSeek compares with other top models in the GPQA benchmark rankings. Notably, DeepSeek is an open-source model (anyone can download the model from the internet), while other common models like Grok, Google Gemini, and ChatGPT are closed-source. As we can see, DeepSeek has largely caught up with the first tier of models. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-14-16-48.png) + +GPQA stands for "Graduate-Level Google-Proof Q&A Benchmark," a graduate-level benchmark for scientific question-answering tasks. Here's a detailed introduction. + +GPQA contains 448 multiple-choice questions covering subfields of biology, physics, and chemistry, such as quantum mechanics, organic chemistry, molecular biology, and more. These questions were written by 61 experts who hold or are pursuing doctoral degrees and have undergone a rigorous validation process. +::: + +Follow these 3 steps to quickly integrate a large model generation API: + +1. **Create an API Key on the DeepSeek platform** +2. **Find the text generation example in the DeepSeek documentation** (there's usually ready-made code you can copy directly) +3. **Open the AI IDE, paste in the API Key + official example**, and tell the AI what functionality to implement: + > Help me integrate this large model's API to support the copywriting generation task for this application + +Next, we'll walk through a demo. You can follow along with the entire process. First, register a [DeepSeek](https://platform.deepseek.com/usage) account, create an API Key, and top up a small amount for testing. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-13-57-41.png) + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-13-58-13.png) + +Click "API KEYS" and find "create new API key" at the bottom of the screen. You'll end up with an API key that looks something like sk-8573341c39fc44315aadc071c53rh7d2. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-13-58-32.png) + +Once you have the key, you have permission to call the model. + +At this point, you can directly read the [API](https://api-docs.deepseek.com/) documentation, which typically provides curl or Python call examples. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-13-58-56.png) + +After finding the example, you can copy all the content from the documentation along with your key into the AI IDE's chat box, asking it to help you integrate the large language model into the prototype you've already developed. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-13-59-31.png) + +Here's a reference prompt: + +``` +Based on this API call method, help me implement a copywriting generation feature that can generate Douyin (TikTok) e-commerce copy in various styles based on product information when clicked. + +Reference materials: +api key: sk-8573341c39aefa1efe +api request reference: +curl \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \ + -d '{ + "model": "deepseek-chat", + "messages": [ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello!"} + ], + "stream": false + }' +``` + +After some AI code generation, you'll easily get a corresponding copywriting generation button to test. If you can't find the entry point, you can ask the AI IDE to tell you which page leads to it. If you really can't find it, you can ask the AI IDE to directly refactor and improve based on your ideas to get the final copywriting generation result. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-14-23-23.png) + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-14-26-35.png) + +Of course, you might be wondering: how do I know it's actually calling the large model and not just returning hardcoded responses? You can enter custom copy and have the large model generate corresponding content based on your custom analysis specified on the spot. + +If you find that the results are different each time and logically coherent, you can be confident that the API is being called correctly. You can also check the [API usage management platform](https://platform.deepseek.com/usage) to see if the calls were successful (though it may take a few minutes to show up). + +# 3. Integrating the Image-to-Text API: Qwen3 VL + +::: info ℹ️ Further Reading on Principles +If you want to learn more about the underlying principles, check out the appendix: [Introduction to Vision Language Models (VLM)](/zh-cn/appendix/8-artificial-intelligence/multimodal-models). + +::: details Learn More: What is Qwen3 VL? + +**Qwen3 VL** is the latest version in the multimodal vision-language model series developed by Alibaba Cloud's Tongyi Qianwen team. VL stands for "Vision-Language," meaning it's a vision-language model. It can understand image content and generate text descriptions based on images, answer questions about images, extract information from images, and more. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-14-48-27.png) +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-14-48-41.png) + +**Key capabilities of Qwen3 VL include:** + +- **Image Understanding**: Can recognize objects, scenes, people, text, and other content in images +- **Visual Q&A**: Accurately answers questions about images based on user queries +- **Image Captioning**: Generates detailed or concise text descriptions of images +- **Multi-image Understanding**: Supports processing multiple images simultaneously for comparative analysis +- **Text Extraction**: Extracts text content from images (OCR capability) + +**Why choose Qwen3 VL?** + +Compared to the previous generation, Qwen3 VL has significantly improved image understanding accuracy and supports longer, more complex image analysis tasks. It excels in Chinese language understanding, has relatively low API call costs, and offers good value for money. Additionally, its larger context window enables it to handle more complex visual reasoning tasks. + +**Typical use cases:** + +- E-commerce: Automatically generate titles, descriptions, and selling points from product images +- Content creation: Automatically generate copy or image suggestions based on reference images +- Office: Image content extraction, automatic report recognition +- Education: Automatic parsing of image-based questions, knowledge point extraction + +::: + +In the previous section, we explained how to integrate a text generation API. But for the application scenario above, we'll notice a problem: we're uploading an image, and if we only use a large language model, it can't understand the content of the image very well, so the generated results may be off. + +We want a model that can help us turn an image into a text description — this requires a Vision Language Model (VLM). In our case, we'll use a vision language model to generate product selling point descriptions, improving the user experience. + +For convenience, we'll use the API provided by [SiliconFlow cloud platform](https://cloud.siliconflow.cn/me) to integrate the image-to-text API. + +::: details Learn More: What is SiliconFlow? +**SiliconFlow** is a well-known AI model aggregation platform in China, providing API services for various mainstream large language models and vision language models. + +**Platform features:** + +- **Multi-model support**: Integrates various mainstream AI models, including DeepSeek, Qwen, Llama series, and other open-source models +- **Technical optimization**: Optimized inference for open-source models, providing low-latency, high-concurrency API services +- **Interface compatibility**: Provides OpenAI-compatible API interfaces for easy integration with existing applications +- **Pay-as-you-go**: Supports usage-based billing + +SiliconFlow is relatively mature in inference services for open-source large models and is a common choice for using domestic open-source AI models. +::: + +Go to the SiliconFlow platform homepage, where you'll see many models to choose from. Find the filter in the upper left corner, click to expand it, select the "Vision" tag, and you'll see many image-to-text models, such as Zhipu GLM-4.6V or Qwen3-VL. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-15-05-04.png) + +You can choose any one to test. Here we'll use `Qwen/Qwen3-VL-8B-Instruct` as an example. + +![](../../../zh-cn/stage-1/1.3-integrating-ai-capabilities/images/index-2026-01-20-15-07-44.png) + +Go to the [SiliconFlow platform](https://cloud.siliconflow.cn/me/account/ak), click "Create New API Key" in the API Keys section to create a new API Key. + +You can directly use the code below as reference code, and send it along with the generated API Key to the AI IDE for feature integration. + +::: details Image-to-Text Reference Code + +```python +from openai import OpenAI +from typing import Dict, Any, List +import base64 +import os +SILICONFLOW_API_KEY: str = "" +SILICONFLOW_BASE_URL: str = "https://api.siliconflow.cn/v1/" +MODEL_NAME: str = "Qwen/Qwen3-VL-8B-Instruct" + +def encode_image(image_path: str) -> str: + with open(image_path, "rb") as image_file: + return base64.b64encode(image_file.read()).decode('utf-8') + +def get_vlm_completion(client: OpenAI, messages: List[Dict[str, Any]]) -> str: + response = client.chat.completions.create( + model=MODEL_NAME, + messages=messages, + max_tokens=512, + temperature=0.7, + top_p=0.7, + frequency_penalty=0.5, + stream=False, + n=1 + ) + return response.choices[0].message.content + +def caption_image(image_path: str) -> str: + base64_image = encode_image(image_path) + messages = [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Please describe this image in detail." + }, + { + "type": "image_url", + "image_url": { + "url": f"data:image/jpeg;base64,{base64_image}" + } + } + ] + } + ] + + client = OpenAI( + api_key=SILICONFLOW_API_KEY, + base_url=SILICONFLOW_BASE_URL + ) + + return get_vlm_completion(client, messages) + +image_path = "images.jpg" +caption = caption_image(image_path) +``` + +::: diff --git a/docs/en-us/stage-2/index.md b/docs/en/stage-2/index.md similarity index 100% rename from docs/en-us/stage-2/index.md rename to docs/en/stage-2/index.md diff --git a/docs/en-us/stage-3/index.md b/docs/en/stage-3/index.md similarity index 100% rename from docs/en-us/stage-3/index.md rename to docs/en/stage-3/index.md diff --git a/docs/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture.md b/docs/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture.md index 1e134ad..f12a822 100644 --- a/docs/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture.md +++ b/docs/zh-cn/appendix/3-browser-and-frontend/frontend-project-architecture.md @@ -1,641 +1,546 @@ # 前端项目架构设计 ::: tip 🎯 核心问题 -**文件越放越乱，代码越写越难找，如何设计一个清晰、可维护的前端项目结构？** 这就像问：你是把所有衣服都扔进一个箱子，还是按季节、类型、颜色分类整理？好的项目架构能让团队协作更高效，让代码维护更轻松。 +**从简单的 HTML 页面到复杂的企业级应用，如何为不同规模的项目选择合适的架构？** 这就像问：从单身公寓到大型商场，如何根据需求设计不同的空间布局？好的架构应该随项目成长而演进，而不是一开始就过度设计。 ::: --- -## 1. 为什么要关注项目架构？ +## 1. 架构演进：从简单到复杂 -### 1.1 从小项目到大项目的演变 +### 1.1 三个复杂度级别概览 -很多初学者刚开始写前端时，项目结构非常简单： +前端项目的架构应该与项目复杂度相匹配。我们按**技术复杂度**和**用户规模**两个维度，将项目分为三个级别： -``` -my-project/ -├── index.html -├── style.css -└── app.js -``` +| 级别 | 技术栈 | 用户规模 | 典型场景 | 核心关注点 | +|------|--------|----------|----------|------------| +| **入门级** | HTML/CSS/JS | 个人/小团队 | 个人博客、宣传页、简单工具 | 快速上线、简单维护 | +| **进阶级** | Vue/React + 构建工具 | 中小型企业 | 管理系统、电商前台、SaaS | 组件复用、状态管理 | +| **企业级** | 框架 + 微前端/SSR | 大型应用 | 大型平台、复杂业务系统 | 性能优化、团队协作、可扩展性 | -三个文件搞定一切，简单直接。但随着项目增长，问题开始出现： +::: tip 💡 如何选择？ +**不要过度设计！** 很多项目从简单的 HTML 开始，随着需求增长逐步引入框架和工具。 -- **页面多了**：`page1.html`, `page2.html`... 文件散落在根目录 -- **组件多了**：按钮、弹窗、表单各自为政，复用困难 -- **工具函数多了**：到处复制粘贴，改一个地方要改十处 -- **样式冲突了**：全局 CSS 互相覆盖，调试困难 - -**问题的本质**：没有"章法"，文件随意存放，就像把春夏秋冬的衣服都扔进一个箱子。 - -### 1.2 好的架构像整理好的衣柜 - -想象一个整理好的衣柜： - -| 区域 | 存放物品 | 特点 | -|------|----------|------| -| **挂衣区** | 外套、衬衫 | 常穿，方便取用 | -| **抽屉区** | 内衣、袜子 | 分类摆放，整齐 | -| **隔板区** | 毛衣、裤子 | 叠放，节省空间 | -| **顶层区** | 换季衣物 | 不常用，收纳起来 | - -**好的项目架构**就是把代码也这样组织：每一类文件有自己的"位置"，团队成员都知道该去哪找、该往哪放。 - -::: tip 💡 通俗比喻：餐厅后厨的组织 -把前端项目想象成一家餐厅的后厨： - -- **`src/pages/`（页面区）** = 出餐口：每个订单对应一个成品菜 -- **`src/components/`（组件区）** = 备料台：切好的蔬菜、调好的酱料，随时可用 -- **`src/utils/`（工具区）** = 工具柜：刀、勺、温度计等通用工具 -- **`src/assets/`（食材区）** = 冷藏库：图片、字体、样式等原材料 -- **`src/services/`（服务层）** = 传菜窗口：与外部（服务员/后端）交互 - -**关键点**：每个区域职责明确，不会混乱。你不会在冷藏库里切菜，也不会把刀具扔进汤锅。 +- 个人项目 → 入门级 +- 创业公司 MVP → 入门级或进阶级 +- 企业管理系统 → 进阶级 +- 大型互联网平台 → 企业级 ::: --- -## 2. 经典目录结构解析 +## 2. 入门级：HTML/CSS/JS 项目 -### 2.1 标准目录结构（以 Vue/React 为例） +### 2.1 适用场景 -一个中大型前端项目的典型结构如下： +- 个人博客、简历页面 +- 产品宣传页（Landing Page） +- 简单的工具页面（计算器、转换器等） +- 原型验证、快速 Demo + +### 2.2 推荐目录结构 ``` -my-frontend-project/ -├── public/ # 静态资源（不经过构建） -│ ├── favicon.ico +my-simple-project/ +├── index.html # 首页 +├── about.html # 关于页面（如有） +├── css/ +│ ├── reset.css # 重置样式 +│ ├── variables.css # CSS 变量（颜色、字体等） +│ ├── components.css # 组件样式（按钮、卡片等） +│ └── main.css # 主样式文件 +├── js/ +│ ├── utils.js # 工具函数 +│ ├── api.js # 简单的 API 调用 +│ └── main.js # 主逻辑 +├── assets/ +│ ├── images/ # 图片资源 +│ └── fonts/ # 字体文件 +└── README.md # 项目说明 +``` + +### 2.3 代码组织原则 + +**HTML**：语义化标签，清晰的结构 + +```html + + + + + + + 我的个人博客 + + + + + + +
+ +
+ +
+
+

文章标题

+

文章内容...

+
+
+ +
+

© 2024 我的博客

+
+ + + + + +``` + +**CSS**：使用 CSS 变量管理主题 + +```css +/* variables.css */ +:root { + --primary-color: #3498db; + --text-color: #333; + --bg-color: #fff; + --spacing-sm: 8px; + --spacing-md: 16px; + --spacing-lg: 24px; + --font-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; +} + +/* components.css - 可复用的组件样式 */ +.btn { + padding: var(--spacing-sm) var(--spacing-md); + border: none; + border-radius: 4px; + background: var(--primary-color); + color: white; + cursor: pointer; +} + +.card { + padding: var(--spacing-md); + border-radius: 8px; + box-shadow: 0 2px 8px rgba(0,0,0,0.1); +} +``` + +**JavaScript**：模块化组织（使用 ES6 模块或简单拆分） + +```javascript +// utils.js +const utils = { + // DOM 操作简化 + $(selector) { + return document.querySelector(selector); + }, + + // 简单的防抖 + debounce(fn, delay) { + let timer; + return function(...args) { + clearTimeout(timer); + timer = setTimeout(() => fn.apply(this, args), delay); + }; + }, + + // 本地存储封装 + storage: { + get(key) { + return JSON.parse(localStorage.getItem(key) || 'null'); + }, + set(key, value) { + localStorage.setItem(key, JSON.stringify(value)); + } + } +}; + +// main.js +document.addEventListener('DOMContentLoaded', () => { + // 页面初始化逻辑 + initNavigation(); + loadBlogPosts(); +}); +``` + +### 2.4 最佳实践 + +✅ **应该做的**： +- 使用语义化 HTML 标签 +- CSS 变量管理颜色和间距 +- 图片压缩和懒加载 +- 添加基础的 SEO meta 标签 + +❌ **避免的**： +- 内联样式（`style="..."`） +- 全局变量污染 +- 重复代码（复制粘贴） + +--- + +## 3. 进阶级：Vue/React 框架项目 + +### 3.1 适用场景 + +- 企业管理系统（ERP、CRM、OA） +- 电商前台/后台 +- SaaS 应用 +- 需要复杂交互的 Web 应用 + +### 3.2 Vue 项目推荐结构 + +``` +my-vue-project/ +├── public/ # 静态资源 │ ├── index.html -│ └── robots.txt +│ └── favicon.ico ├── src/ -│ ├── assets/ # 项目资源（会被构建工具处理） -│ │ ├── images/ -│ │ ├── fonts/ -│ │ └── styles/ -│ │ ├── variables.scss # 变量定义 -│ │ ├── mixins.scss # 混入样式 -│ │ └── global.css # 全局样式 +│ ├── assets/ # 样式、图片、字体 +│ │ ├── styles/ +│ │ │ ├── variables.scss +│ │ │ ├── mixins.scss +│ │ │ └── global.scss +│ │ └── images/ │ ├── components/ # 通用组件 -│ │ ├── common/ # 全局通用组件 +│ │ ├── common/ # 全局通用（Button、Modal 等） │ │ │ ├── Button/ │ │ │ │ ├── index.vue -│ │ │ │ ├── Button.scss -│ │ │ │ └── Button.test.js -│ │ │ ├── Modal/ -│ │ │ └── Loading/ -│ │ └── business/ # 业务组件 -│ │ ├── UserCard/ -│ │ └── ProductList/ -│ ├── views/ 或 pages/ # 页面组件 +│ │ │ │ └── Button.scss +│ │ │ └── Modal/ +│ │ └── business/ # 业务组件（UserCard 等） +│ ├── views/ # 页面组件 │ │ ├── Home/ -│ │ ├── About/ -│ │ └── User/ -│ │ ├── Profile/ -│ │ └── Settings/ -│ ├── router/ 或 navigation/ # 路由配置 +│ │ ├── User/ +│ │ │ ├── List.vue +│ │ │ └── Detail.vue +│ │ └── Product/ +│ ├── router/ # 路由配置 │ │ └── index.js -│ ├── stores/ 或 state/ # 状态管理 +│ ├── stores/ # Pinia/Vuex 状态管理 │ │ ├── user.js │ │ └── app.js -│ ├── services/ 或 api/ # API 服务 +│ ├── services/ # API 服务 +│ │ ├── request.js # axios 封装 │ │ ├── user.js │ │ └── product.js -│ ├── utils/ 或 helpers/ # 工具函数 -│ │ ├── request.js # 请求封装 -│ │ ├── storage.js # 本地存储 -│ │ └── format.js # 格式化工具 -│ ├── hooks/ 或 composables/ # 组合式函数 +│ ├── utils/ # 工具函数 +│ │ ├── format.js +│ │ ├── validate.js +│ │ └── storage.js +│ ├── composables/ # 组合式函数 │ │ ├── useAuth.js │ │ └── useLoading.js -│ ├── directives/ # 自定义指令 -│ ├── plugins/ # 插件配置 │ ├── constants/ # 常量定义 -│ ├── types/ 或 @types/ # TypeScript 类型 -│ └── App.vue 或 App.jsx # 根组件 -│ └── main.js 或 main.ts # 入口文件 +│ │ └── index.js +│ ├── App.vue +│ └── main.js ├── tests/ # 测试文件 -│ ├── unit/ -│ └── e2e/ ├── .env # 环境变量 -├── .env.development -├── .env.production -├── vite.config.js # 构建配置 +├── vite.config.js ├── package.json └── README.md ``` -::: tip 📊 从图解中你能看到什么？ -**分层逻辑**： - -- **`public/` vs `src/assets/`**：前者直接复制到输出目录，后者会被构建工具处理（压缩、转译、添加哈希值） -- **`components/` vs `views/`**：组件是"零件"，页面是"成品"。一个页面由多个组件组装而成 -- **`services/` 独立出来**：把 API 调用集中管理，方便统一处理错误、加载状态、请求拦截 - -**依赖方向**： +### 3.3 React 项目推荐结构 ``` -views/pages → components → utils/hooks - ↓ -services → stores +my-react-project/ +├── public/ +├── src/ +│ ├── assets/ +│ ├── components/ +│ │ ├── common/ # 通用组件 +│ │ │ ├── Button/ +│ │ │ │ ├── index.jsx +│ │ │ │ └── Button.module.css +│ │ │ └── Modal/ +│ │ └── business/ # 业务组件 +│ ├── pages/ # 页面组件 +│ │ ├── Home/ +│ │ ├── User/ +│ │ └── Product/ +│ ├── hooks/ # 自定义 Hooks +│ │ ├── useAuth.js +│ │ └── useFetch.js +│ ├── services/ # API 服务 +│ │ ├── api.js +│ │ └── userService.js +│ ├── store/ # Redux/Zustand 状态管理 +│ │ ├── slices/ +│ │ └── index.js +│ ├── utils/ +│ ├── constants/ +│ ├── App.jsx +│ └── main.jsx +├── tests/ +└── package.json ``` -上层可以调用下层，但下层不应该依赖上层。 -::: +### 3.4 关键概念详解 -### 2.2 按功能组织 vs 按类型组织 +#### 组件设计原则 -项目结构有两种主流的组织方式： +**单一职责**：一个组件只做一件事 -#### 方式一：按类型组织（Type-based） +```vue + + + + + +``` + +#### 状态管理策略 + +| 状态类型 | 存储位置 | 示例 | +|----------|----------|------| +| **全局状态** | Pinia/Redux | 用户信息、登录状态、主题设置 | +| **页面状态** | 页面组件 | 列表查询条件、分页信息 | +| **组件状态** | 组件内部 | 表单输入、弹窗显示/隐藏 | +| **服务端状态** | TanStack Query/SWR | 服务器数据、缓存 | + +#### 目录组织方式选择 + +**方式一：按类型组织（适合小型项目）** ``` src/ -├── components/ -│ ├── Button.vue -│ ├── Modal.vue -│ └── Card.vue -├── views/ -│ ├── Home.vue -│ ├── User.vue -│ └── Product.vue -├── stores/ -│ ├── user.js -│ └── product.js -└── services/ - ├── user.js - └── product.js +├── components/ # 所有组件 +├── views/ # 所有页面 +├── stores/ # 所有状态 +└── services/ # 所有服务 ``` -**优点**： -- 结构清晰，同类文件在一起 -- 适合小型项目，一目了然 - -**缺点**： -- 修改一个功能要跨多个目录 -- 大型项目中文件过多，难以定位 - -#### 方式二：按功能组织（Feature-based） +**方式二：按功能组织（适合中大型项目）** ``` src/ ├── features/ -│ ├── auth/ -│ │ ├── components/ -│ │ │ ├── LoginForm.vue -│ │ │ └── RegisterForm.vue -│ │ ├── stores/ -│ │ │ └── authStore.js -│ │ ├── services/ -│ │ │ └── authApi.js -│ │ ├── hooks/ -│ │ │ └── useAuth.js -│ │ └── index.js # 统一导出 -│ ├── user/ -│ │ ├── components/ -│ │ ├── stores/ -│ │ └── services/ -│ └── product/ -│ ├── components/ -│ ├── stores/ -│ └── services/ -├── shared/ # 共享资源 -│ ├── components/ -│ ├── utils/ -│ └── styles/ +│ ├── auth/ # 认证功能的所有代码 +│ ├── user/ # 用户功能的所有代码 +│ └── product/ # 商品功能的所有代码 +├── shared/ # 共享资源 └── App.vue ``` -**优点**： -- 高内聚，修改一个功能在一个目录完成 -- 便于团队协作，不同人负责不同 feature -- 易于删除或重构，不会散落各处 - -**缺点**： -- 初期设计需要考虑 feature 划分 -- 共享组件需要额外考虑 - ::: tip 💡 如何选择？ -| 项目规模 | 推荐方式 | 原因 | -|----------|----------|------| -| 小型项目（< 10 个页面） | 按类型组织 | 简单直接，快速上手 | -| 中大型项目（> 20 个页面） | 按功能组织 | 便于维护，团队协作 | -| 微前端/大型应用 | 按功能 + 模块拆分 | 独立部署，团队自治 | - -**实际建议**：很多项目采用"混合模式"——整体按功能组织，内部按类型细分。 +- 项目页面 < 10 个 → 按类型组织 +- 项目页面 > 20 个 → 按功能组织 +- 团队 > 5 人 → 按功能组织，便于并行开发 ::: --- -## 3. 各目录的职责与最佳实践 +## 4. 企业级：大型应用架构 -### 3.1 `components/` 组件目录 +### 4.1 适用场景 -组件是前端项目的核心，良好的组件设计能大幅提升开发效率。 +- 大型互联网平台（电商、社交、内容平台） +- 复杂的企业级应用 +- 需要支持多团队协作的项目 +- 对性能和可维护性要求极高的项目 -#### 组件分类 +### 4.2 微前端架构 + +当项目规模大到一定程度，单个代码库难以维护时，可以考虑**微前端**架构。 ``` -components/ -├── common/ # 通用组件（跨项目可复用） -│ ├── Button/ -│ ├── Input/ -│ ├── Modal/ -│ └── Loading/ -├── business/ # 业务组件（项目特定） -│ ├── UserCard/ -│ ├── ProductItem/ -│ └── OrderTable/ -└── layout/ # 布局组件 - ├── Header/ - ├── Sidebar/ - └── Footer/ +大型电商平台/ +├── 基座应用（主框架） +│ ├── 顶部导航 +│ ├── 侧边菜单 +│ ├── 用户中心入口 +│ └── 子应用容器 +├── 商品子应用（独立部署） +│ ├── 商品列表 +│ ├── 商品详情 +│ └── 商品管理 +├── 订单子应用（独立部署） +│ ├── 购物车 +│ ├── 订单列表 +│ └── 支付流程 +├── 用户子应用（独立部署） +│ ├── 个人中心 +│ ├── 收货地址 +│ └── 优惠券 +└── 营销子应用（独立部署） + ├── 活动页面 + ├── 优惠券发放 + └── 积分商城 ``` -#### 单文件组件结构 +**微前端的优势**： +- 团队自治：每个子应用独立开发、部署 +- 技术栈无关：不同团队可以用不同框架 +- 渐进式升级：可以逐步重构老系统 -每个组件建议包含以下文件： +### 4.3 企业级目录结构 ``` -Button/ -├── index.vue # 主组件（或 .tsx/.jsx） -├── Button.scss # 样式（可选 CSS Modules） -├── Button.test.js # 单元测试 -├── Button.stories.js # Storybook 文档（可选） -├── types.ts # 类型定义（TS 项目） -└── index.ts # 统一导出 +enterprise-project/ +├── apps/ # 微前端子应用 +│ ├── main/ # 基座应用 +│ ├── product/ +│ ├── order/ +│ └── user/ +├── packages/ # 共享包（Monorepo） +│ ├── ui-components/ # 通用组件库 +│ ├── utils/ # 工具函数 +│ ├── constants/ # 常量定义 +│ └── types/ # TypeScript 类型 +├── shared/ # 共享配置 +│ ├── eslint-config/ +│ ├── ts-config/ +│ └── vite-config/ +├── docs/ # 项目文档 +├── scripts/ # 构建脚本 +└── package.json ``` -::: details 📝 组件代码示例 -```vue - - +### 4.4 性能优化架构 - - - -``` -::: - -### 3.2 `views/` 或 `pages/` 页面目录 - -页面是用户看到的"成品"，通常对应路由。 +大型应用需要关注性能优化： ``` -views/ -├── Home/ # 首页 -│ ├── index.vue -│ ├── components/ # 页面私有组件 -│ │ ├── HeroSection.vue -│ │ └── FeatureList.vue -│ └── hooks/ # 页面私有 hooks -│ └── useHomeData.js -├── User/ -│ ├── Profile/ -│ ├── Settings/ -│ └── OrderHistory/ -└── Product/ - ├── List/ - └── Detail/ +性能优化策略/ +├── 构建时优化 +│ ├── 代码分割（Code Splitting） +│ ├── 路由懒加载 +│ ├── Tree Shaking +│ └── 资源压缩 +├── 运行时优化 +│ ├── 虚拟滚动（长列表） +│ ├── 图片懒加载 +│ ├── 组件按需渲染 +│ └── 缓存策略 +└── 网络优化 + ├── CDN 加速 + ├── HTTP 缓存 + ├── 资源预加载 + └── Service Worker ``` -**最佳实践**： -- 页面组件保持"薄"，逻辑下沉到 hooks 或 services -- 页面私有组件放在页面目录下，避免污染全局 -- 复杂页面可以进一步拆分子目录 +### 4.5 SSR/SSG 架构 -### 3.3 `services/` 或 `api/` 服务层 +对于需要 SEO 或首屏性能的场景： -集中管理所有 API 调用，统一处理请求/响应拦截。 - -``` -services/ -├── request.js # 请求实例配置（axios/fetch 封装） -├── user.js # 用户相关 API -├── product.js # 商品相关 API -├── order.js # 订单相关 API -└── index.js # 统一导出 -``` - -::: details 📝 服务层代码示例 -```javascript -// services/request.js -import axios from 'axios' -import { useAuthStore } from '@/stores/auth' - -const request = axios.create({ - baseURL: import.meta.env.VITE_API_BASE_URL, - timeout: 10000 -}) - -// 请求拦截器 -request.interceptors.request.use( - (config) => { - const authStore = useAuthStore() - if (authStore.token) { - config.headers.Authorization = `Bearer ${authStore.token}` - } - return config - } -) - -// 响应拦截器 -request.interceptors.response.use( - (response) => response.data, - (error) => { - if (error.response?.status === 401) { - // 统一处理登录过期 - window.location.href = '/login' - } - return Promise.reject(error) - } -) - -export default request -``` - -```javascript -// services/user.js -import request from './request' - -export const userApi = { - login: (data) => request.post('/auth/login', data), - register: (data) => request.post('/auth/register', data), - getProfile: () => request.get('/user/profile'), - updateProfile: (data) => request.put('/user/profile', data) -} -``` -::: - -### 3.4 `stores/` 状态管理 - -``` -stores/ -├── index.js # store 入口 -├── auth.js # 认证状态 -├── user.js # 用户信息 -├── app.js # 应用级状态（主题、语言等） -└── cart.js # 购物车状态 -``` - -**建议**： -- 按功能拆分 store，避免单个文件过大 -- 区分全局状态和局部状态，不要什么都放全局 -- 使用组合式 API（Pinia/Vuex 4+）更灵活 - -### 3.5 `utils/` 工具函数 - -``` -utils/ -├── format.js # 格式化（日期、金额等） -├── storage.js # 本地存储封装 -├── validate.js # 表单验证 -├── dom.js # DOM 操作 -├── date.js # 日期处理 -└── index.js # 统一导出 -``` - -**原则**： -- 纯函数优先，便于测试 -- 单一职责，一个函数只做一件事 -- 添加 JSDoc 注释，说明参数和返回值 - -::: details 📝 工具函数示例 -```javascript -// utils/storage.js -const STORAGE_PREFIX = 'myapp_' - -export const storage = { - get(key) { - const value = localStorage.getItem(STORAGE_PREFIX + key) - try { - return JSON.parse(value) - } catch { - return value - } - }, - - set(key, value) { - localStorage.setItem( - STORAGE_PREFIX + key, - typeof value === 'string' ? value : JSON.stringify(value) - ) - }, - - remove(key) { - localStorage.removeItem(STORAGE_PREFIX + key) - } -} -``` -::: - -### 3.6 `hooks/` 或 `composables/` 组合式函数 - -``` -hooks/ -├── useAuth.js # 认证逻辑 -├── useLoading.js # 加载状态 -├── usePagination.js # 分页逻辑 -├── useForm.js # 表单处理 -└── useWebsocket.js # WebSocket -``` - -::: details 📝 Hook 示例 -```javascript -// hooks/useLoading.js -import { ref } from 'vue' - -export function useLoading() { - const loading = ref(false) - - const withLoading = async (fn) => { - loading.value = true - try { - return await fn() - } finally { - loading.value = false - } - } - - return { loading, withLoading } -} - -// 使用 -const { loading, withLoading } = useLoading() -const fetchData = () => withLoading(async () => { - const data = await api.getData() - list.value = data -}) -``` -::: +| 方案 | 适用场景 | 代表框架 | +|------|----------|----------| +| **SSR** | 需要 SEO、首屏渲染快 | Next.js、Nuxt.js | +| **SSG** | 内容静态、更新不频繁 | Astro、VitePress | +| **混合** | 部分静态、部分动态 | Next.js (ISR) | --- -## 4. 知名开源项目的架构参考 +## 5. 按用户量级别的架构选择 -### 4.1 Vue 3 官方仓库 +### 5.1 个人/小团队（日活 < 1000） -``` -vue/ -├── packages/ -│ ├── vue/ # 核心包 -│ ├── reactivity/ # 响应式系统 -│ ├── runtime-core/ # 运行时核心 -│ ├── runtime-dom/ # DOM 运行时 -│ ├── compiler-sfc/ # 单文件组件编译器 -│ └── shared/ # 共享工具 -├── scripts/ # 构建脚本 -└── tsconfig.json -``` +**特点**：快速迭代、资源有限、需求变化快 -**特点**： -- Monorepo 结构，多个包统一管理 -- 按功能拆分 package，职责清晰 -- 共享工具提取到 shared 包 +**推荐架构**： +- 技术栈：Vue 3 + Vite 或 React + Vite +- 状态管理：Pinia 或 Zustand（轻量级） +- UI 库：Element Plus / Ant Design +- 部署：Vercel / Netlify / 云服务器 -### 4.2 React 官方仓库 +**目录结构**：简单按类型组织即可 -``` -react/ -├── packages/ -│ ├── react/ # React 核心 -│ ├── react-dom/ # DOM 渲染器 -│ ├── react-reconciler/ # 协调器 -│ ├── scheduler/ # 调度器 -│ └── shared/ # 共享代码 -├── fixtures/ # 测试用例 -└── scripts/ -``` +### 5.2 中型企业（日活 1k-100k） -**特点**： -- 核心与渲染器分离（react vs react-dom） -- reconciler 独立，支持多平台 -- scheduler 单独抽离，可独立使用 +**特点**：业务复杂、团队协作、需要稳定性 -### 4.3 Ant Design Vue +**推荐架构**： +- 技术栈：Vue 3 + TypeScript 或 React + TypeScript +- 状态管理：Pinia + 组合式函数 或 Redux Toolkit +- UI 库：自建组件库 + 业务组件库 +- 测试：单元测试 + E2E 测试 +- 部署：CI/CD 流水线 + Docker -``` -ant-design-vue/ -├── components/ # 组件目录 -│ ├── button/ -│ ├── modal/ -│ └── ... -├── docs/ # 文档 -├── site/ # 官网 -├── tests/ # 测试 -└── typings/ # 类型定义 -``` +**目录结构**：按功能组织，建立规范 -**特点**： -- 组件与文档分离 -- 每个组件独立目录，包含 demo、test、style -- 统一的类型定义 +### 5.3 大型平台（日活 > 100k） -### 4.4 Next.js（全栈框架） +**特点**：高并发、多团队协作、长期维护 -``` -my-nextjs-app/ -├── app/ # App Router（新版） -│ ├── page.js # 页面 -│ ├── layout.js # 布局 -│ ├── loading.js # 加载状态 -│ └── api/ # API 路由 -├── components/ # 组件 -├── lib/ # 工具函数 -├── public/ # 静态资源 -└── styles/ # 全局样式 -``` +**推荐架构**： +- 技术栈：React/Vue + TypeScript（严格模式） +- 架构：微前端 + Monorepo +- 状态管理：细粒度状态管理 + 服务端状态缓存 +- 性能：SSR/SSG + CDN + 边缘计算 +- 监控：前端监控 + 错误追踪 + 性能分析 -**特点**： -- 约定式路由，文件即路由 -- 内置 loading、error、layout 等约定文件 -- API 路由与页面共存 +**目录结构**：Monorepo + 微前端 --- -## 5. 架构设计原则与检查清单 +## 6. 架构演进路线图 -### 5.1 核心原则 +### 6.1 演进示例：从博客到平台 -| 原则 | 说明 | 实践建议 | -|------|------|----------| -| **单一职责** | 一个模块只做一件事 | 组件、函数保持简洁 | -| **高内聚低耦合** | 相关代码放在一起，减少依赖 | 按功能组织目录 | -| **可预测性** | 代码行为符合直觉 | 命名清晰，结构一致 | -| **可测试性** | 便于编写单元测试 | 纯函数、依赖注入 | -| **可扩展性** | 新功能容易添加 | 预留扩展点，避免硬编码 | +``` +阶段 1：个人博客（HTML/CSS/JS） + ↓ 需求：需要后台管理 +阶段 2：增加管理后台（Vue/React + 简单结构） + ↓ 需求：用户系统、评论功能 +阶段 3：功能模块化（按功能组织） + ↓ 需求：多团队协作、独立部署 +阶段 4：微前端架构（Monorepo） +``` -### 5.2 检查清单 +### 6.2 何时该升级架构？ -**目录结构**： -- [ ] 是否有清晰的目录划分？ -- [ ] 新成员能否快速找到文件位置？ -- [ ] 是否避免了过深的嵌套（建议不超过 4 层）？ - -**组件设计**： -- [ ] 组件是否单一职责？ -- [ ] Props 是否清晰、可预测？ -- [ ] 是否提取了可复用的逻辑到 hooks？ - -**代码组织**： -- [ ] 是否避免了循环依赖？ -- [ ] 工具函数是否纯函数优先？ -- [ ] 常量、配置是否集中管理？ - -**团队协作**： -- [ ] 是否有编码规范文档？ -- [ ] 是否有文件命名约定？ -- [ ] 代码审查是否关注架构问题？ +| 信号 | 说明 | 建议 | +|------|------|------| +| 构建时间 > 5 分钟 | 项目过大 | 代码分割、微前端 | +| 多人频繁冲突 | 协作困难 | 按功能组织、模块拆分 | +| 改一处崩多处 | 耦合严重 | 重构、加强测试 | +| 首屏加载 > 3 秒 | 性能问题 | 懒加载、SSR、优化 | +| 新成员上手慢 | 结构混乱 | 文档、规范、重构 | --- -## 6. 总结 +## 7. 总结 ::: tip 💡 核心思想 -好的前端项目架构不是一成不变的，而是随着项目发展不断演进的。关键是建立清晰的**组织原则**和**命名约定**，让团队成员达成共识。 +**架构没有银弹，适合的才是最好的。** + +- **小项目**不要过度设计，HTML/CSS/JS 足够 +- **中项目**建立规范，组件化、模块化 +- **大项目**考虑微前端、性能优化、团队协作 **记住这几点**： -1. **先简单后复杂**：小项目不要过度设计 -2. **按功能组织**：中大型项目推荐 Feature-based -3. **统一约定**：命名、结构、代码风格保持一致 -4. **持续重构**：定期审视架构，及时调整 +1. **渐进式演进**：从简单开始，随需求增长 +2. **统一约定**：命名、结构、代码风格保持一致 +3. **文档先行**：架构决策要记录，便于传承 +4. **定期重构**：技术债务要及时偿还 -**最终目标**：让代码像整理好的衣柜一样，想找什么立刻能找到，新成员也能快速上手。 +**最终目标**：让代码像整理好的空间一样，无论大小，都能高效运转。 ::: --- @@ -646,3 +551,4 @@ my-nextjs-app/ - [React 项目结构建议](https://react.dev/learn/thinking-in-react) - [Bulletproof React - 架构指南](https://github.com/alan2207/bulletproof-react) - [Feature Sliced Design](https://feature-sliced.design/) +- [微前端架构](https://micro-frontends.org/) diff --git a/docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md b/docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md index 5ca5971..565e088 100644 --- a/docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md +++ b/docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md @@ -1,751 +1,958 @@ # 后端项目架构设计 ::: tip 🎯 核心问题 -**API 越写越多，代码越来越乱，如何设计一个清晰、可维护的后端项目结构？** 这就像问：你是把所有工具都扔进一个抽屉，还是按功能分类整理？好的项目架构能让团队协作更高效，让系统扩展更轻松。 +**从简单的脚本到大型分布式系统，如何为不同规模、不同语言的后端项目选择合适的架构？** 这就像问：从家庭作坊到大型工厂，如何根据产量和工艺设计不同的生产线？好的后端架构应该随业务成长而演进，同时充分发挥语言特性。 ::: --- -## 1. 为什么要关注后端项目架构？ +## 1. 架构演进：从脚本到系统 -### 1.1 从小脚本到大系统的演变 +### 1.1 按用户量划分架构级别 -很多初学者刚开始写后端时，代码结构非常简单： +后端项目的架构应该与业务规模和用户量相匹配： -```python -# app.py - 所有代码在一个文件 -from flask import Flask, request, jsonify -import sqlite3 +| 级别 | 用户量 | 并发量 | 典型场景 | 核心关注点 | +|------|--------|--------|----------|------------| +| **入门级** | < 1k | < 100 | 个人项目、MVP、内部工具 | 快速开发、简单部署 | +| **进阶级** | 1k-100k | 100-10k | 企业系统、SaaS、中小平台 | 分层架构、代码规范 | +| **企业级** | > 100k | > 10k | 大型平台、互联网应用 | 微服务、高可用、性能优化 | -app = Flask(__name__) +### 1.2 按语言特性选择架构风格 -@app.route('/users', methods=['GET']) -def get_users(): - conn = sqlite3.connect('db.sqlite') - users = conn.execute('SELECT * FROM users').fetchall() - return jsonify(users) +不同编程语言有不同的设计哲学和生态，架构设计应该顺应语言特性： -@app.route('/users', methods=['POST']) -def create_user(): - data = request.json - conn = sqlite3.connect('db.sqlite') - conn.execute('INSERT INTO users (name, email) VALUES (?, ?)', - (data['name'], data['email'])) - conn.commit() - return jsonify({'message': 'User created'}) +| 语言 | 设计哲学 | 推荐架构风格 | 代表框架 | +|------|----------|--------------|----------| +| **Node.js** | 事件驱动、非阻塞 I/O | 分层架构 + 异步流程 | Express、NestJS、Fastify | +| **Python** | 简洁优雅、快速开发 | MTV/MVC、分层架构 | Django、Flask、FastAPI | +| **Go** | 简单高效、并发原生 | 简洁分层、微服务 | Gin、Echo、Fiber | +| **Java** | 企业级、强类型 | 严格分层、领域驱动 | Spring Boot、Spring Cloud | -# 还有订单、商品、支付...所有接口都在这个文件 -``` - -几百行代码搞定一切，简单直接。但随着业务发展，问题开始出现： - -- **接口多了**：一个文件几千行，找代码像"考古" -- **逻辑复杂了**：业务规则散落在各处，修改容易遗漏 -- **数据库操作重复**：到处写 SQL，改表结构要改几十处 -- **测试困难**：代码耦合严重，单元测试难以编写 - -**问题的本质**：没有"章法"，所有的逻辑都堆在一起，就像把所有的工具、零件、说明书都扔进一个抽屉。 - -### 1.2 好的架构像整理好的车间 - -想象一个整理好的工厂车间： - -| 区域 | 功能 | 特点 | -|------|------|------| -| **原料区** | 存放原材料 | 分类摆放，标签清晰 | -| **加工区** | 生产加工 | 流水线作业，工序明确 | -| **质检区** | 质量检查 | 统一标准，严格把关 | -| **成品区** | 存放成品 | 整齐有序，易于出库 | -| **工具室** | 存放工具 | 按需借用，用完归还 | - -**好的后端架构**就是把代码也这样组织：每一层只关心自己的职责，数据像流水一样在各层之间传递。 - -::: tip 💡 通俗比喻：餐厅后厨的组织 -把后端系统想象成一家餐厅的后厨： - -- **`controllers/`（出餐口）** = 服务员接单：接收订单、核对信息、上菜 -- **`services/`（厨师团队）** = 厨师做菜：按照菜谱加工、协调各工序 -- **`repositories/`（仓库管理）** = 仓管取料：从仓库取食材、记录库存 -- **`models/`（菜谱标准）** = 菜谱定义：宫保鸡丁需要什么料、什么口味 -- **`utils/`（工具柜）** = 厨具存放：刀、勺、秤等通用工具 - -**关键点**：每个角色职责明确，不会越界。服务员不会自己炒菜，厨师不会擅自改菜谱。 +::: tip 💡 架构选择原则 +1. **不要过度设计**：小项目用简单架构，大项目才需要复杂架构 +2. **顺应语言特性**：不要试图在 Python 里写 Java 风格的代码 +3. **渐进式演进**：从简单开始，随业务增长逐步优化 +4. **团队熟悉度**：选择团队熟悉的架构风格，降低学习成本 ::: --- -## 2. 经典分层架构详解 +## 2. 入门级架构（用户量 < 1k） -### 2.1 四层架构（Controller-Service-Repository-Model） +### 2.1 适用场景 -最经典的后端分层架构如下： +- 个人项目、学习练习 +- 创业公司 MVP（最小可行产品） +- 内部工具、管理后台 +- 原型验证、概念演示 + +### 2.2 Node.js - 简洁脚本风格 + +**特点**：单文件或简单拆分，快速上线 ``` -my-backend-project/ +my-node-api/ ├── src/ -│ ├── controllers/ # 控制器层（Controller） -│ │ ├── userController.js -│ │ ├── orderController.js -│ │ └── index.js -│ ├── services/ # 业务逻辑层（Service） -│ │ ├── userService.js -│ │ ├── orderService.js -│ │ └── index.js -│ ├── repositories/ # 数据访问层（Repository/DAO） -│ │ ├── userRepository.js -│ │ └── index.js -│ ├── models/ # 数据模型层（Model/Entity） -│ │ ├── user.js -│ │ ├── order.js -│ │ └── index.js -│ ├── middlewares/ # 中间件 -│ │ ├── auth.js -│ │ ├── errorHandler.js -│ │ └── validator.js -│ ├── utils/ # 工具函数 -│ │ ├── logger.js -│ │ ├── response.js -│ │ └── validator.js -│ ├── config/ # 配置文件 -│ │ ├── database.js -│ │ ├── redis.js -│ │ └── index.js -│ ├── routes/ # 路由定义 -│ │ ├── userRoutes.js -│ │ ├── index.js -│ │ └── api.js -│ ├── jobs/ 或 workers/ # 定时任务/后台任务 -│ │ └── emailWorker.js -│ ├── events/ 或 subscribers/ # 事件监听 -│ │ └── userEvents.js -│ └── app.js # 应用入口 -├── tests/ # 测试文件 -│ ├── unit/ -│ ├── integration/ -│ └── e2e/ -├── migrations/ # 数据库迁移 -├── seeds/ # 种子数据 -├── docs/ # 文档 -├── .env # 环境变量 +│ ├── app.js # 应用入口 +│ ├── routes.js # 路由定义 +│ ├── db.js # 数据库连接 +│ └── utils.js # 工具函数 +├── .env # 环境变量 ├── package.json └── README.md ``` -::: tip 📊 从图解中你能看到什么？ -**分层逻辑**： +**代码示例**： -``` -┌─────────────────────────────────────────┐ -│ Controller 层（控制器层） │ ← 接待员：接收请求，返回响应 -│ - 接收 HTTP 请求 │ -│ - 参数校验、权限检查 │ -│ - 调用 Service │ -│ - 格式化响应 │ -├─────────────────────────────────────────┤ -│ Service 层（业务逻辑层） │ ← 厨师：处理核心业务 -│ - 业务逻辑编排 │ -│ - 事务管理 │ -│ - 调用 Repository │ -│ - 跨模块协调 │ -├─────────────────────────────────────────┤ -│ Repository 层（数据访问层） │ ← 仓管员：管理数据存取 -│ - 数据库操作 │ -│ - ORM 封装 │ -│ - 查询构建 │ -├─────────────────────────────────────────┤ -│ Model 层（数据模型层） │ ← 菜谱标准：定义数据结构 -│ - 实体定义（Entity） │ -│ - 类型定义 │ -│ - 业务规则验证 │ -└─────────────────────────────────────────┘ -``` - -**依赖方向**： -``` -Controller → Service → Repository → Model - ↓ - Middleware / Utils -``` - -上层依赖下层，下层不依赖上层。Model 是核心，所有层都可能依赖它。 -::: - -### 2.2 各层职责详解 - -#### Controller 层：请求的"接待员" - -Controller 是系统的"门面"，负责接收 HTTP 请求并返回响应。 - -**职责**： -- 接收和解析请求参数 -- 调用相应的 Service 处理业务 -- 格式化响应数据 -- 处理 HTTP 相关逻辑（状态码、Header 等） - -**不应该做的事**： -- 直接操作数据库 -- 编写复杂业务逻辑 -- 处理事务 - -::: details 📝 Controller 代码示例（Node.js/Express） ```javascript -// controllers/userController.js -const userService = require('../services/userService') -const { success, error } = require('../utils/response') +// src/app.js +const express = require('express'); +const app = express(); -class UserController { - // 获取用户列表 - async list(req, res) { - try { - const { page = 1, limit = 10 } = req.query - const users = await userService.getUsers({ page, limit }) - return success(res, users) - } catch (err) { - return error(res, err.message, 500) - } - } +app.use(express.json()); - // 获取单个用户 - async getById(req, res) { - try { - const { id } = req.params - const user = await userService.getUserById(id) - if (!user) { - return error(res, 'User not found', 404) - } - return success(res, user) - } catch (err) { - return error(res, err.message, 500) - } - } +// 路由直接写在入口（适合接口很少的情况） +app.get('/users', async (req, res) => { + const users = await db.query('SELECT * FROM users'); + res.json(users); +}); - // 创建用户 - async create(req, res) { - try { - const userData = req.body - const newUser = await userService.createUser(userData) - return success(res, newUser, 201) - } catch (err) { - return error(res, err.message, 400) - } - } +app.post('/users', async (req, res) => { + const { name, email } = req.body; + const result = await db.query( + 'INSERT INTO users (name, email) VALUES (?, ?)', + [name, email] + ); + res.status(201).json({ id: result.insertId }); +}); + +app.listen(3000, () => { + console.log('Server running on port 3000'); +}); +``` + +**参考开源项目**： +- [expressjs/express](https://github.com/expressjs/express) - 官方示例 +- [vercel/micro](https://github.com/vercel/micro) - 微服务风格 + +### 2.3 Python - 快速原型风格 + +**特点**：利用 Python 的简洁性，快速实现功能 + +``` +my-python-api/ +├── app.py # 主应用 +├── models.py # 数据模型 +├── config.py # 配置 +├── requirements.txt +└── README.md +``` + +**代码示例（Flask）**： + +```python +# app.py +from flask import Flask, request, jsonify +from flask_sqlalchemy import SQLAlchemy + +app = Flask(__name__) +app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db' +db = SQLAlchemy(app) + +# 模型定义 +class User(db.Model): + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String(80), nullable=False) + email = db.Column(db.String(120), unique=True, nullable=False) + +# 路由 +@app.route('/users', methods=['GET']) +def get_users(): + users = User.query.all() + return jsonify([{'id': u.id, 'name': u.name, 'email': u.email} for u in users]) + +@app.route('/users', methods=['POST']) +def create_user(): + data = request.json + user = User(name=data['name'], email=data['email']) + db.session.add(user) + db.session.commit() + return jsonify({'id': user.id}), 201 + +if __name__ == '__main__': + app.run(debug=True) +``` + +**参考开源项目**： +- [pallets/flask](https://github.com/pallets/flask) - 官方示例 +- [tiangolo/fastapi](https://github.com/tiangolo/fastapi) - 现代异步风格 + +### 2.4 Go - 简洁标准库风格 + +**特点**：利用 Go 的标准库，最少的依赖 + +``` +my-go-api/ +├── main.go # 入口 +├── handlers.go # 处理器 +├── models.go # 模型 +├── db.go # 数据库 +├── go.mod +└── README.md +``` + +**代码示例**： + +```go +// main.go +package main + +import ( + "database/sql" + "encoding/json" + "log" + "net/http" + _ "github.com/mattn/go-sqlite3" +) + +type User struct { + ID int `json:"id"` + Name string `json:"name"` + Email string `json:"email"` } -module.exports = new UserController() -``` -::: +var db *sql.DB -#### Service 层：业务的"厨师" - -Service 是系统的"大脑"，包含核心业务逻辑。 - -**职责**： -- 实现业务规则和流程 -- 协调多个 Repository 完成复杂操作 -- 管理事务 -- 数据转换和计算 - -**不应该做的事**： -- 直接处理 HTTP 请求/响应 -- 直接操作数据库（通过 Repository） - -::: details 📝 Service 代码示例 -```javascript -// services/userService.js -const userRepository = require('../repositories/userRepository') -const orderRepository = require('../repositories/orderRepository') -const emailService = require('./emailService') -const { hashPassword } = require('../utils/crypto') - -class UserService { - // 获取用户列表 - async getUsers({ page, limit }) { - const offset = (page - 1) * limit - const [users, total] = await Promise.all([ - userRepository.findAll({ limit, offset }), - userRepository.count() - ]) - - return { - data: users, - pagination: { - page, - limit, - total, - totalPages: Math.ceil(total / limit) - } - } - } - - // 获取用户详情（包含订单信息） - async getUserById(id) { - const user = await userRepository.findById(id) - if (!user) return null - - // 获取用户订单统计 - const orderStats = await orderRepository.getStatsByUserId(id) - - return { - ...user, - orderStats - } - } - - // 创建用户（包含事务和邮件通知） - async createUser(userData) { - // 检查邮箱是否已存在 - const existingUser = await userRepository.findByEmail(userData.email) - if (existingUser) { - throw new Error('Email already exists') +func main() { + var err error + db, err = sql.Open("sqlite3", "./app.db") + if err != nil { + log.Fatal(err) } - // 密码加密 - const hashedPassword = await hashPassword(userData.password) - - // 创建用户 - const newUser = await userRepository.create({ - ...userData, - password: hashedPassword - }) - - // 发送欢迎邮件（异步，不阻塞） - emailService.sendWelcomeEmail(newUser.email).catch(console.error) - - return newUser - } + http.HandleFunc("/users", usersHandler) + log.Println("Server starting on :8080") + log.Fatal(http.ListenAndServe(":8080", nil)) } -module.exports = new UserService() -``` -::: - -#### Repository 层：数据的"仓管员" - -Repository 负责所有与数据存储相关的操作。 - -**职责**： -- 数据库的增删改查 -- ORM 映射 -- 查询优化 - -**不应该做的事**： -- 包含业务逻辑 -- 处理事务（由 Service 控制） - -::: details 📝 Repository 代码示例 -```javascript -// repositories/userRepository.js -const { User } = require('../models') - -class UserRepository { - // 查询所有用户 - async findAll({ limit, offset }) { - return await User.findAll({ - limit, - offset, - attributes: { exclude: ['password'] } // 不返回密码 - }) - } - - // 根据 ID 查询 - async findById(id) { - return await User.findByPk(id, { - attributes: { exclude: ['password'] } - }) - } - - // 根据邮箱查询 - async findByEmail(email) { - return await User.findOne({ where: { email } }) - } - - // 创建用户 - async create(data) { - return await User.create(data) - } - - // 更新用户 - async update(id, data) { - const user = await User.findByPk(id) - if (!user) return null - return await user.update(data) - } - - // 删除用户 - async delete(id) { - const user = await User.findByPk(id) - if (!user) return null - await user.destroy() - return true - } - - // 统计用户数量 - async count() { - return await User.count() - } +func usersHandler(w http.ResponseWriter, r *http.Request) { + switch r.Method { + case http.MethodGet: + getUsers(w, r) + case http.MethodPost: + createUser(w, r) + } } -module.exports = new UserRepository() -``` -::: +func getUsers(w http.ResponseWriter, r *http.Request) { + rows, _ := db.Query("SELECT id, name, email FROM users") + defer rows.Close() -#### Model 层：数据的"定义" - -Model 定义数据结构和业务规则。 - -::: details 📝 Model 代码示例（Sequelize） -```javascript -// models/user.js -const { DataTypes } = require('sequelize') -const { sequelize } = require('../config/database') - -const User = sequelize.define('User', { - id: { - type: DataTypes.UUID, - defaultValue: DataTypes.UUIDV4, - primaryKey: true - }, - name: { - type: DataTypes.STRING(100), - allowNull: false, - validate: { - len: [2, 100] + var users []User + for rows.Next() { + var u User + rows.Scan(&u.ID, &u.Name, &u.Email) + users = append(users, u) } - }, - email: { - type: DataTypes.STRING(255), - allowNull: false, - unique: true, - validate: { - isEmail: true - } - }, - password: { - type: DataTypes.STRING(255), - allowNull: false - }, - status: { - type: DataTypes.ENUM('active', 'inactive', 'banned'), - defaultValue: 'active' - } -}, { - tableName: 'users', - timestamps: true, // 自动添加 createdAt 和 updatedAt - indexes: [ - { fields: ['email'] }, - { fields: ['status'] } - ] -}) -module.exports = User + json.NewEncoder(w).Encode(users) +} ``` -::: + +**参考开源项目**： +- [golang/go](https://github.com/golang/go) - 标准库示例 +- [go-chi/chi](https://github.com/go-chi/chi) - 轻量级路由 + +### 2.5 Java - Spring Boot 起步风格 + +**特点**：利用 Spring Boot 的自动配置，快速启动 + +``` +my-spring-app/ +├── src/main/java/com/example/ +│ ├── controller/ +│ │ └── UserController.java +│ ├── model/ +│ │ └── User.java +│ ├── repository/ +│ │ └── UserRepository.java +│ └── Application.java +├── src/main/resources/ +│ └── application.yml +├── pom.xml +└── README.md +``` + +**代码示例**： + +```java +// Application.java +@SpringBootApplication +public class Application { + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } +} + +// User.java +@Entity +public class User { + @Id + @GeneratedValue(strategy = GenerationType.IDENTITY) + private Long id; + private String name; + private String email; + // getters and setters +} + +// UserRepository.java +public interface UserRepository extends JpaRepository { +} + +// UserController.java +@RestController +@RequestMapping("/users") +public class UserController { + @Autowired + private UserRepository userRepository; + + @GetMapping + public List getAllUsers() { + return userRepository.findAll(); + } + + @PostMapping + public User createUser(@RequestBody User user) { + return userRepository.save(user); + } +} +``` + +**参考开源项目**： +- [spring-projects/spring-boot](https://github.com/spring-projects/spring-boot) - 官方示例 +- [spring-projects/spring-petclinic](https://github.com/spring-projects/spring-petclinic) - 经典示例 --- -## 3. 其他重要目录 +## 3. 进阶级架构（用户量 1k-100k） -### 3.1 `middlewares/` 中间件 +### 3.1 适用场景 -中间件是请求处理流程中的"过滤器"。 +- 企业管理系统（ERP、CRM、OA） +- SaaS 应用 +- 电商平台 +- 需要多团队协作的项目 + +### 3.2 分层架构详解 + +进阶级项目推荐采用**四层架构**（Controller-Service-Repository-Model）： ``` -middlewares/ -├── auth.js # 认证中间件 -├── errorHandler.js # 错误处理 -├── validator.js # 参数校验 -├── rateLimiter.js # 限流 -├── logger.js # 请求日志 -└── cors.js # 跨域处理 -``` - -::: details 📝 中间件示例 -```javascript -// middlewares/auth.js -const jwt = require('jsonwebtoken') - -const authMiddleware = (req, res, next) => { - const token = req.headers.authorization?.split(' ')[1] - - if (!token) { - return res.status(401).json({ message: 'No token provided' }) - } - - try { - const decoded = jwt.verify(token, process.env.JWT_SECRET) - req.user = decoded - next() - } catch (err) { - return res.status(401).json({ message: 'Invalid token' }) - } -} - -module.exports = authMiddleware -``` -::: - -### 3.2 `routes/` 路由 - -集中管理所有 API 路由。 - -```javascript -// routes/userRoutes.js -const express = require('express') -const router = express.Router() -const userController = require('../controllers/userController') -const authMiddleware = require('../middlewares/auth') - -// 公开路由 -router.get('/', userController.list) -router.get('/:id', userController.getById) - -// 需要认证的路由 -router.post('/', authMiddleware, userController.create) -router.put('/:id', authMiddleware, userController.update) -router.delete('/:id', authMiddleware, userController.delete) - -module.exports = router -``` - -```javascript -// routes/index.js -const express = require('express') -const router = express.Router() - -router.use('/users', require('./userRoutes')) -router.use('/orders', require('./orderRoutes')) -router.use('/products', require('./productRoutes')) - -module.exports = router -``` - -### 3.3 `config/` 配置 - -集中管理所有配置，支持多环境。 - -```javascript -// config/index.js -const env = process.env.NODE_ENV || 'development' - -const configs = { - development: { - port: 3000, - database: { - host: 'localhost', - port: 5432, - name: 'myapp_dev' - }, - redis: { - host: 'localhost', - port: 6379 - } - }, - production: { - port: process.env.PORT || 80, - database: { - host: process.env.DB_HOST, - port: process.env.DB_PORT, - name: process.env.DB_NAME - } - } -} - -module.exports = configs[env] -``` - -### 3.4 `utils/` 工具 - -``` -utils/ -├── logger.js # 日志工具 -├── response.js # 响应封装 -├── crypto.js # 加密解密 -├── date.js # 日期处理 -└── validator.js # 验证工具 -``` - ---- - -## 4. 按功能组织（Feature-based） - -对于中大型项目，可以采用按功能组织的方式： - -``` -src/ -├── features/ -│ ├── users/ -│ │ ├── users.controller.js -│ │ ├── users.service.js -│ │ ├── users.repository.js -│ │ ├── users.model.js -│ │ ├── users.routes.js -│ │ ├── users.validator.js -│ │ └── index.js # 统一导出 -│ ├── orders/ -│ │ ├── orders.controller.js -│ │ ├── orders.service.js -│ │ └── ... -│ └── products/ -│ ├── products.controller.js -│ └── ... -├── shared/ # 共享资源 -│ ├── middlewares/ -│ ├── utils/ -│ └── config/ -└── app.js -``` - -**优点**： -- 高内聚，一个功能的所有代码在一起 -- 便于团队协作，不同人负责不同 feature -- 易于删除或重构 - ---- - -## 5. 知名开源项目的架构参考 - -### 5.1 Express.js 官方示例 - -``` -express-example/ -├── bin/ # 启动脚本 -├── public/ # 静态资源 -├── routes/ # 路由 -├── views/ # 视图模板 -├── app.js # 应用配置 -└── package.json -``` - -**特点**：简单直接，适合小型项目。 - -### 5.2 NestJS（企业级 Node.js 框架） - -``` -nestjs-project/ +project/ ├── src/ -│ ├── modules/ # 功能模块 +│ ├── controllers/ # 控制层：处理 HTTP 请求 +│ ├── services/ # 服务层：业务逻辑 +│ ├── repositories/ # 数据层：数据访问 +│ ├── models/ # 模型层：数据结构 +│ ├── middlewares/ # 中间件 +│ ├── utils/ # 工具函数 +│ ├── config/ # 配置 +│ └── routes/ # 路由定义 +├── tests/ +├── docs/ +└── scripts/ +``` + +### 3.3 Node.js - 企业级分层 + +**参考开源项目**： +- [nestjs/nest](https://github.com/nestjs/nest) - 企业级 Node.js 框架 +- [goldbergyoni/nodebestpractices](https://github.com/goldbergyoni/nodebestpractices) - Node.js 最佳实践 + +``` +node-enterprise/ +├── src/ +│ ├── modules/ # 按功能模块组织 │ │ ├── users/ │ │ │ ├── users.controller.ts │ │ │ ├── users.service.ts +│ │ │ ├── users.repository.ts │ │ │ ├── users.module.ts │ │ │ └── dto/ -│ │ └── orders/ +│ │ ├── orders/ +│ │ └── products/ │ ├── common/ # 共享模块 -│ ├── config/ # 配置 -│ └── main.ts # 入口 +│ │ ├── filters/ # 异常过滤器 +│ │ ├── guards/ # 守卫 +│ │ ├── interceptors/ # 拦截器 +│ │ └── pipes/ # 管道 +│ ├── config/ +│ └── main.ts ``` -**特点**： -- 强制模块化结构 -- 内置依赖注入 -- 适合大型项目 +**NestJS 代码示例**： -### 5.3 Django（Python） +```typescript +// users/users.controller.ts +@Controller('users') +export class UsersController { + constructor(private readonly usersService: UsersService) {} + + @Get() + findAll(@Query() query: QueryUserDto) { + return this.usersService.findAll(query); + } + + @Post() + create(@Body() createUserDto: CreateUserDto) { + return this.usersService.create(createUserDto); + } +} + +// users/users.service.ts +@Injectable() +export class UsersService { + constructor( + @InjectRepository(User) + private usersRepository: Repository, + ) {} + + async findAll(query: QueryUserDto) { + const [data, total] = await this.usersRepository.findAndCount({ + skip: (query.page - 1) * query.limit, + take: query.limit, + }); + return { data, total }; + } + + async create(createUserDto: CreateUserDto) { + const user = this.usersRepository.create(createUserDto); + return this.usersRepository.save(user); + } +} +``` + +### 3.4 Python - Django/DRF 风格 + +**参考开源项目**： +- [django/django](https://github.com/django/django) - 官方项目 +- [encode/django-rest-framework](https://github.com/encode/django-rest-framework) - REST 框架 +- [cookiecutter/cookiecutter-django](https://github.com/cookiecutter/cookiecutter-django) - 项目模板 ``` -django-project/ -├── project_name/ # 项目配置 +django-enterprise/ ├── apps/ │ ├── users/ # 用户应用 │ │ ├── models.py -│ │ ├── views.py -│ │ ├── serializers.py -│ │ └── urls.py -│ └── orders/ # 订单应用 +│ │ ├── views.py # API 视图 +│ │ ├── serializers.py # 序列化器 +│ │ ├── permissions.py # 权限 +│ │ ├── urls.py +│ │ └── tests/ +│ ├── orders/ +│ └── products/ +├── config/ # 项目配置 +│ ├── settings/ +│ │ ├── base.py +│ │ ├── development.py +│ │ └── production.py +│ ├── urls.py +│ └── wsgi.py +├── utils/ # 共享工具 ├── templates/ ├── static/ └── manage.py ``` -**特点**： -- 约定优于配置 -- MTV（Model-Template-View）模式 -- 应用可复用 +**Django REST Framework 代码示例**： -### 5.4 Spring Boot（Java） +```python +# users/models.py +from django.contrib.auth.models import AbstractUser + +class User(AbstractUser): + phone = models.CharField(max_length=20, blank=True) + avatar = models.URLField(blank=True) + +# users/serializers.py +from rest_framework import serializers + +class UserSerializer(serializers.ModelSerializer): + class Meta: + model = User + fields = ['id', 'username', 'email', 'phone', 'avatar'] + +# users/views.py +from rest_framework import viewsets, permissions +from rest_framework.decorators import action + +class UserViewSet(viewsets.ModelViewSet): + queryset = User.objects.all() + serializer_class = UserSerializer + permission_classes = [permissions.IsAuthenticated] + + @action(detail=False, methods=['get']) + def me(self, request): + serializer = self.get_serializer(request.user) + return Response(serializer.data) + +# users/urls.py +from rest_framework.routers import DefaultRouter + +router = DefaultRouter() +router.register(r'users', UserViewSet) + +urlpatterns = router.urls +``` + +### 3.5 Go - 整洁架构风格 + +**参考开源项目**： +- [gin-gonic/gin](https://github.com/gin-gonic/gin) - Web 框架 +- [go-kit/kit](https://github.com/go-kit/kit) - 微服务工具包 +- [bxcodec/go-clean-arch](https://github.com/bxcodec/go-clean-arch) - 整洁架构示例 ``` -spring-boot-project/ -├── src/main/java/ -│ └── com/example/ -│ ├── controller/ -│ ├── service/ -│ ├── repository/ -│ ├── entity/ -│ ├── dto/ -│ ├── config/ -│ └── Application.java +go-enterprise/ +├── cmd/ +│ └── api/ # 应用入口 +│ └── main.go +├── internal/ # 私有代码 +│ ├── domain/ # 领域层（实体、接口） +│ │ ├── user.go +│ │ └── repository.go +│ ├── usecase/ # 用例层（业务逻辑） +│ │ └── user_usecase.go +│ ├── delivery/ # 传输层（HTTP/gRPC） +│ │ └── http/ +│ │ └── user_handler.go +│ ├── repository/ # 仓库层（数据访问） +│ │ └── user_repository.go +│ └── config/ +├── pkg/ # 公共库 +├── migrations/ +└── go.mod +``` + +**整洁架构代码示例**： + +```go +// domain/user.go +type User struct { + ID int64 `json:"id"` + Username string `json:"username"` + Email string `json:"email"` + CreatedAt time.Time `json:"created_at"` +} + +// domain/repository.go +type UserRepository interface { + GetByID(ctx context.Context, id int64) (*User, error) + GetByEmail(ctx context.Context, email string) (*User, error) + Create(ctx context.Context, user *User) error + Update(ctx context.Context, user *User) error +} + +// usecase/user_usecase.go +type UserUsecase struct { + userRepo UserRepository +} + +func (u *UserUsecase) GetByID(ctx context.Context, id int64) (*User, error) { + return u.userRepo.GetByID(ctx, id) +} + +func (u *UserUsecase) Create(ctx context.Context, user *User) error { + // 业务逻辑：检查邮箱是否已存在 + existing, _ := u.userRepo.GetByEmail(ctx, user.Email) + if existing != nil { + return errors.New("email already exists") + } + return u.userRepo.Create(ctx, user) +} + +// delivery/http/user_handler.go +type UserHandler struct { + UserUsecase *usecase.UserUsecase +} + +func (h *UserHandler) GetUser(c *gin.Context) { + id, _ := strconv.ParseInt(c.Param("id"), 10, 64) + user, err := h.UserUsecase.GetByID(c.Request.Context(), id) + if err != nil { + c.JSON(404, gin.H{"error": "user not found"}) + return + } + c.JSON(200, user) +} +``` + +### 3.6 Java - Spring Boot 企业级 + +**参考开源项目**： +- [spring-projects/spring-boot](https://github.com/spring-projects/spring-boot) +- [spring-cloud-samples](https://github.com/spring-cloud-samples) - 微服务示例 +- [ali-baba/spring-cloud-alibaba](https://github.com/alibaba/spring-cloud-alibaba) - 阿里微服务 + +``` +spring-enterprise/ +├── src/main/java/com/example/ +│ ├── application/ # 应用层 +│ │ ├── controller/ # 控制器 +│ │ ├── dto/ # 数据传输对象 +│ │ └── assembler/ # 组装器 +│ ├── domain/ # 领域层 +│ │ ├── entity/ # 实体 +│ │ ├── valueobject/ # 值对象 +│ │ ├── repository/ # 仓库接口 +│ │ └── service/ # 领域服务 +│ ├── infrastructure/ # 基础设施层 +│ │ ├── repository/ # 仓库实现 +│ │ ├── config/ # 配置 +│ │ └── common/ # 工具类 +│ └── Application.java ├── src/main/resources/ │ ├── application.yml │ └── mapper/ └── src/test/ ``` -**特点**： -- 严格的分层架构 -- 注解驱动开发 -- 强大的生态 +**领域驱动设计（DDD）代码示例**： + +```java +// domain/entity/User.java +@Entity +@Table(name = "users") +public class User { + @Id + @GeneratedValue(strategy = GenerationType.IDENTITY) + private Long id; + + @Column(nullable = false) + private String username; + + @Column(nullable = false, unique = true) + private String email; + + @Embedded + private UserStatus status; + + // 领域方法 + public void deactivate() { + this.status = UserStatus.INACTIVE; + } + + public boolean isActive() { + return this.status == UserStatus.ACTIVE; + } +} + +// domain/repository/UserRepository.java +public interface UserRepository { + Optional findById(Long id); + Optional findByEmail(String email); + User save(User user); + void delete(User user); +} + +// application/controller/UserController.java +@RestController +@RequestMapping("/api/v1/users") +@RequiredArgsConstructor +public class UserController { + private final UserService userService; + private final UserAssembler userAssembler; + + @GetMapping("/{id}") + public ResponseEntity getUser(@PathVariable Long id) { + User user = userService.findById(id); + return ResponseEntity.ok(userAssembler.toDTO(user)); + } + + @PostMapping + public ResponseEntity createUser(@RequestBody @Valid CreateUserRequest request) { + User user = userService.createUser(request); + return ResponseEntity.status(HttpStatus.CREATED) + .body(userAssembler.toDTO(user)); + } +} + +// infrastructure/repository/UserRepositoryImpl.java +@Repository +@RequiredArgsConstructor +public class UserRepositoryImpl implements UserRepository { + private final UserJpaRepository jpaRepository; + + @Override + public Optional findById(Long id) { + return jpaRepository.findById(id); + } + + @Override + public User save(User user) { + return jpaRepository.save(user); + } +} +``` --- -## 6. 架构设计原则与检查清单 +## 4. 企业级架构（用户量 > 100k） -### 6.1 核心原则 +### 4.1 适用场景 -| 原则 | 说明 | 实践建议 | -|------|------|----------| -| **单一职责** | 一个模块只做一件事 | Controller 只处理 HTTP，Service 只处理业务 | -| **依赖倒置** | 依赖抽象而非具体实现 | 使用接口/抽象类 | -| **开闭原则** | 对扩展开放，对修改关闭 | 新增功能不修改原有代码 | -| **DRY** | 不要重复自己 | 提取公共逻辑到 utils 或基类 | -| **KISS** | 保持简单 | 不要过度设计 | +- 大型互联网平台 +- 金融交易系统 +- 高并发电商系统 +- 需要多团队协作的大型项目 -### 6.2 检查清单 +### 4.2 微服务架构 -**分层检查**： -- [ ] Controller 是否只处理 HTTP 相关逻辑？ -- [ ] Service 是否包含核心业务逻辑？ -- [ ] Repository 是否只负责数据访问？ -- [ ] 层与层之间是否通过明确的接口交互？ +当单体应用无法满足需求时，需要考虑微服务架构： -**代码质量**： -- [ ] 是否有统一的错误处理机制？ -- [ ] 是否使用环境变量管理配置？ -- [ ] 是否有日志记录？ -- [ ] 是否编写了单元测试？ +``` +microservices-platform/ +├── api-gateway/ # API 网关 +│ ├── src/ +│ └── Dockerfile +├── services/ # 业务服务 +│ ├── user-service/ # 用户服务 +│ ├── order-service/ # 订单服务 +│ ├── product-service/ # 商品服务 +│ └── payment-service/ # 支付服务 +├── shared/ # 共享库 +│ ├── proto/ # Protocol Buffers +│ ├── common-lib/ +│ └── event-contracts/ +├── infrastructure/ # 基础设施 +│ ├── docker-compose.yml +│ ├── kubernetes/ +│ └── terraform/ +└── docs/ +``` -**安全**： -- [ ] 敏感配置是否放入环境变量？ -- [ ] 是否有输入验证？ -- [ ] 是否有认证和授权？ -- [ ] 密码是否加密存储？ +### 4.3 各语言微服务框架 + +| 语言 | 微服务框架 | 服务发现 | 配置中心 | 链路追踪 | +|------|------------|----------|----------|----------| +| **Node.js** | NestJS + gRPC | Consul | etcd | Jaeger | +| **Python** | FastAPI + Nameko | Eureka | Consul | Zipkin | +| **Go** | Go-kit + gRPC | etcd | etcd | OpenTelemetry | +| **Java** | Spring Cloud | Nacos | Nacos | SkyWalking | + +### 4.4 代码库设计（Monorepo vs Polyrepo） + +**Monorepo（单一代码库）**： + +``` +monorepo/ +├── services/ +│ ├── user-service/ # 独立服务 +│ │ ├── src/ +│ │ ├── package.json +│ │ └── Dockerfile +│ ├── order-service/ +│ └── product-service/ +├── shared/ +│ ├── types/ # 共享类型 +│ ├── utils/ # 共享工具 +│ └── proto/ # 共享协议 +├── packages/ +│ ├── eslint-config/ # 共享 ESLint 配置 +│ └── ts-config/ # 共享 TS 配置 +├── docker-compose.yml +└── package.json # 根 package.json +``` + +**优点**： +- 代码共享方便 +- 统一构建和发布 +- 重构容易 + +**缺点**： +- 代码库庞大 +- 权限管理复杂 + +**Polyrepo（多代码库）**： + +每个服务独立仓库： +- `github.com/company/user-service` +- `github.com/company/order-service` +- `github.com/company/shared-lib` + +**优点**： +- 服务独立演进 +- 团队自治 +- 权限清晰 + +**缺点**： +- 代码共享困难 +- 版本管理复杂 + +### 4.5 数据层设计 + +**数据库选择策略**： + +| 数据类型 | 推荐数据库 | 适用场景 | +|----------|------------|----------| +| 关系型数据 | PostgreSQL | 用户、订单、商品 | +| 缓存 | Redis | 会话、热点数据 | +| 搜索 | Elasticsearch | 商品搜索、日志 | +| 时序数据 | InfluxDB/TimescaleDB | 监控、指标 | +| 文档数据 | MongoDB | 日志、配置 | + +**数据访问层设计**： + +``` +data-layer/ +├── primary-db/ # 主数据库 +│ ├── master/ # 写库 +│ └── slaves/ # 读库 +├── cache-layer/ # 缓存层 +│ ├── redis-cluster/ +│ └── local-cache/ +├── search-engine/ # 搜索引擎 +│ └── elasticsearch/ +└── message-queue/ # 消息队列 + ├── kafka/ + └── rabbitmq/ +``` + +--- + +## 5. 开源项目架构规范参考 + +### 5.1 Node.js 生态 + +**Express.js 官方项目结构**： +``` +express-project/ +├── bin/ # 启动脚本 +├── public/ # 静态资源 +├── routes/ # 路由 +├── views/ # 视图 +├── app.js # 应用配置 +└── package.json +``` + +**NestJS 官方推荐**： +``` +nest-project/ +├── src/ +│ ├── modules/ # 功能模块 +│ ├── common/ # 共享模块 +│ ├── config/ +│ └── main.ts +├── test/ +└── nest-cli.json +``` + +### 5.2 Python 生态 + +**Django 官方项目结构**： +``` +django-project/ +├── project_name/ # 项目配置 +├── apps/ # 应用目录 +├── templates/ +├── static/ +├── media/ +└── manage.py +``` + +**FastAPI 项目结构**： +``` +fastapi-project/ +├── app/ +│ ├── api/ +│ │ ├── deps.py # 依赖 +│ │ └── v1/ +│ │ └── endpoints/ +│ ├── core/ # 核心配置 +│ ├── db/ # 数据库 +│ ├── models/ # 模型 +│ ├── schemas/ # Pydantic 模型 +│ └── main.py +├── tests/ +└── alembic/ # 迁移 +``` + +### 5.3 Go 生态 + +**标准项目布局**： +``` +go-project/ +├── cmd/ # 应用入口 +│ └── app/ +│ └── main.go +├── internal/ # 私有代码 +├── pkg/ # 公共库 +├── api/ # API 定义 +├── web/ # 静态资源 +├── configs/ # 配置 +├── scripts/ # 脚本 +└── go.mod +``` + +**参考**： +- [golang-standards/project-layout](https://github.com/golang-standards/project-layout) + +### 5.4 Java 生态 + +**Spring Boot 官方结构**： +``` +spring-boot-project/ +├── src/main/java/com/example/ +│ ├── controller/ +│ ├── service/ +│ ├── repository/ +│ ├── entity/ +│ ├── dto/ +│ ├── config/ +│ └── Application.java +├── src/main/resources/ +│ ├── static/ +│ ├── templates/ +│ └── application.yml +└── src/test/ +``` + +**阿里巴巴 Java 开发手册**： +- 分层清晰：controller/service/manager/dao +- 领域模型：DO/DTO/BO/VO 区分 +- 包结构：按功能模块划分 + +--- + +## 6. 架构演进路线图 + +### 6.1 演进示例 + +``` +阶段 1：单体应用（入门级） + ↓ 用户量增长、团队扩大 +阶段 2：分层架构（进阶级） + ↓ 业务复杂、多团队协作 +阶段 3：模块化/微服务（企业级） + ↓ 高并发、高可用要求 +阶段 4：云原生架构（平台级） +``` + +### 6.2 何时升级架构？ + +| 信号 | 当前级别 | 建议升级 | +|------|----------|----------| +| 代码文件 > 50 个 | 入门级 | 进阶级 | +| 构建时间 > 5 分钟 | 进阶级 | 模块化 | +| 团队 > 10 人 | 进阶级 | 微服务 | +| 日活 > 10 万 | 进阶级 | 企业级 | +| 多语言技术栈 | 单体 | 微服务 | --- ## 7. 总结 ::: tip 💡 核心思想 -好的后端架构应该像一家组织良好的餐厅： +**架构服务于业务，不是为架构而架构。** -- **分工明确**：每个角色知道自己的职责 -- **流程清晰**：数据像流水一样在各层之间传递 -- **易于扩展**：新增功能不会破坏现有结构 -- **便于测试**：各层可以独立测试 +**按用户量选择**： +- **< 1k**：简单脚本，快速上线 +- **1k-100k**：分层架构，代码规范 +- **> 100k**：微服务，高可用设计 -**记住这几点**： -1. **分层是手段，不是目的**：不要为了分层而分层 -2. **按功能组织**：中大型项目推荐 Feature-based -3. **统一约定**：命名、结构、错误处理保持一致 -4. **持续重构**：定期审视架构，及时调整 +**按语言选择**： +- **Node.js**：利用异步特性，适合 I/O 密集型 +- **Python**：快速开发，适合数据处理和 AI +- **Go**：高性能，适合云原生和微服务 +- **Java**：企业级，适合大型复杂系统 -**最终目标**：让代码像整理好的车间一样，想找什么立刻能找到，新功能容易添加，旧代码容易维护。 +**通用原则**： +1. **渐进式演进**：从简单开始，随业务增长 +2. **约定优于配置**：统一规范，降低沟通成本 +3. **自动化测试**：保证重构安全 +4. **文档先行**：架构决策要记录 + +**最终目标**：让代码像工厂车间一样，无论规模大小，都能高效运转。 ::: --- ## 参考资源 -- [NestJS 文档](https://docs.nestjs.com/) -- [Express 最佳实践](https://expressjs.com/en/advanced/best-practice-security.html) -- [Bulletproof Node.js](https://github.com/santiq/bulletproof-nodejs) -- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) +### 开源项目 +- [nestjs/nest](https://github.com/nestjs/nest) - Node.js 企业级框架 +- [django/django](https://github.com/django/django) - Python Web 框架 +- [gin-gonic/gin](https://github.com/gin-gonic/gin) - Go Web 框架 +- [spring-projects/spring-boot](https://github.com/spring-projects/spring-boot) - Java 框架 + +### 架构指南 +- [goldbergyoni/nodebestpractices](https://github.com/goldbergyoni/nodebestpractices) - Node.js 最佳实践 +- [golang-standards/project-layout](https://github.com/golang-standards/project-layout) - Go 项目布局 +- [cookiecutter/cookiecutter-django](https://github.com/cookiecutter/cookiecutter-django) - Django 项目模板 +- [ali-baba/spring-cloud-alibaba](https://github.com/alibaba/spring-cloud-alibaba) - 阿里微服务 + +### 书籍 +- 《Clean Architecture》- Robert C. Martin +- 《Building Microservices》- Sam Newman +- 《Designing Data-Intensive Applications》- Martin Kleppmann diff --git a/docs/zh-cn/appendix/5-data/data-governance.md b/docs/zh-cn/appendix/5-data/data-governance.md index 1b777f2..a3fbe9c 100644 --- a/docs/zh-cn/appendix/5-data/data-governance.md +++ b/docs/zh-cn/appendix/5-data/data-governance.md @@ -1,3 +1,214 @@ # 数据治理与数据质量 -> 待实现 +::: tip 前言 +**你有没有遇到过这种情况：报表上的数字和实际业务对不上，两个系统里同一个用户的信息不一样，或者分析结果因为脏数据完全不可信？** 数据治理就是解决这些问题的系统性方法。在"数据驱动决策"的时代，数据质量直接决定了决策质量——垃圾进，垃圾出（Garbage In, Garbage Out）。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **数据质量维度**：理解完整性、准确性、一致性等六大质量维度 +- **数据治理体系**：了解从组织、流程到技术的治理框架 +- **数据血缘**：掌握数据从源头到消费的全链路追踪 +- **元数据管理**：理解"描述数据的数据"的重要性 +- **数据分层架构**：掌握 ODS → DWD → DWS → ADS 的数仓分层模型 +- **实战能力**：知道如何在项目中落地数据治理 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 数据质量维度 | 完整性、准确性、一致性、时效性 | +| **第 2 章** | 数据治理框架 | 组织、流程、技术、文化 | +| **第 3 章** | 数据血缘追踪 | 影响分析、问题排查、合规审计 | +| **第 4 章** | 元数据管理 | 技术元数据、业务元数据、操作元数据 | +| **第 5 章** | 数据分层架构 | ODS、DWD、DWS、ADS | +| **第 6 章** | 治理工具与实践 | Great Expectations、dbt、DataHub | + +--- + +## 0. 全景图：为什么需要数据治理？ + +数据治理不是一个技术问题，而是一个**管理问题**。它回答的核心问题是：**谁对数据负责？数据的标准是什么？如何保证数据持续可信？** + +想象一个公司有 100 个数据表，每个表由不同团队维护，没有统一的命名规范、没有数据字典、没有质量检查。结果就是：同一个"月活用户"指标，市场部算出来 500 万，产品部算出来 300 万——因为定义不一样。 + +::: tip 数据治理的四个支柱 +1. **组织**：明确数据 Owner、数据管家（Data Steward）的角色和职责 +2. **流程**：建立数据接入、变更、下线的标准流程 +3. **技术**：部署数据质量监控、元数据管理、血缘追踪等工具 +4. **文化**：让全公司认同"数据是资产"，而不是"数据是副产品" +::: + +--- + +## 1. 数据质量的六个维度 + +数据质量不是一个模糊的概念，而是可以从六个具体维度来衡量的。每个维度都有明确的定义和检测方法。 + + + +| 维度 | 定义 | 检测方法 | 常见问题 | +|------|------|---------|---------| +| 完整性 | 数据是否存在缺失 | 空值率检查 | 必填字段为空、关联数据缺失 | +| 准确性 | 数据是否正确 | 规则校验、抽样核对 | 金额为负、日期不合法 | +| 一致性 | 多源数据是否一致 | 跨系统比对 | CRM 和订单系统用户名不同 | +| 时效性 | 数据是否及时更新 | 更新时间检查 | 库存数据滞后、价格未同步 | +| 唯一性 | 是否存在重复记录 | 去重检查 | 同一用户注册两次 | +| 有效性 | 是否符合格式规则 | 正则/范围校验 | 邮箱格式错误、年龄为负数 | + +::: tip 数据质量的 1-10-100 法则 +- **1 元**：在数据入口做校验，预防脏数据进入 +- **10 元**：在数据仓库中清洗已有的脏数据 +- **100 元**：因为脏数据导致错误决策的损失 + +越早发现和修复数据质量问题，成本越低。 +::: + +--- + +## 2. 数据治理框架：全生命周期管理 + +数据治理不是一次性项目，而是贯穿数据全生命周期的持续过程。从数据的产生到销毁，每个阶段都需要明确的规范和责任人。 + + + +| 阶段 | 核心产出 | 关键角色 | +|------|---------|---------| +| 定义标准 | 数据字典、命名规范、分类分级标准 | 数据架构师 | +| 采集接入 | 接入规范、校验规则、血缘记录 | 数据工程师 | +| 存储管理 | 分层模型、权限矩阵、生命周期策略 | DBA / 平台工程师 | +| 使用消费 | 数据目录、脱敏规则、质量报告 | 数据分析师 / 业务方 | +| 归档销毁 | 归档策略、删除记录、审计日志 | 安全合规团队 | + +## 2. 数据治理框架 + +数据治理不是买一个工具就能解决的，它需要一套完整的框架来支撑。业界最常用的参考框架是 DAMA-DMBOK（数据管理知识体系）。 + +| 治理领域 | 核心内容 | 关键产出 | +|---------|---------|---------| +| 数据架构 | 定义数据模型、数据流、存储策略 | 数据架构图、ER 图 | +| 数据标准 | 统一命名规范、编码规范、指标定义 | 数据字典、指标库 | +| 数据质量 | 建立质量规则、监控告警、修复流程 | 质量报告、SLA 仪表盘 | +| 数据安全 | 分级分类、访问控制、脱敏加密 | 安全策略、审计日志 | +| 主数据管理 | 统一客户、商品等核心实体的"黄金记录" | 主数据中心 | +| 数据生命周期 | 管理数据从创建到归档到销毁的全过程 | 保留策略、归档规则 | + +::: tip 数据治理的成熟度模型 +- **Level 1 - 初始级**：没有统一标准，各团队各自为政 +- **Level 2 - 可重复级**：有基本的规范文档，但执行不一致 +- **Level 3 - 已定义级**：有统一的治理流程和工具，大部分团队遵守 +- **Level 4 - 已管理级**：有量化的质量指标和自动化监控 +- **Level 5 - 优化级**：持续改进，数据治理融入日常开发流程 +::: + +--- + +## 3. 数据血缘：从哪来，到哪去 + +数据血缘（Data Lineage）记录了数据从源头到最终消费的完整流转路径。它就像数据的"族谱"，让你能追溯任何一个数据的来龙去脉。 + + + +数据血缘在实际工作中有三个核心应用场景： + +| 场景 | 问题 | 血缘如何帮助 | +|------|------|------------| +| 影响分析 | 要修改用户表的字段，会影响哪些下游报表？ | 沿血缘向下追踪所有依赖 | +| 根因定位 | 今天的 GMV 报表数据异常，问题出在哪一步？ | 沿血缘向上回溯每个环节 | +| 合规审计 | 用户的手机号经过了哪些系统？是否都做了脱敏？ | 追踪敏感字段的全链路流转 | + +::: tip 血缘采集的两种方式 +- **主动采集**：解析 SQL 语句、ETL 配置，自动提取表级/字段级血缘关系 +- **被动采集**：通过 Hook 拦截查询引擎（如 Hive、Spark）的执行计划，实时记录血缘 + +主流工具如 Apache Atlas、DataHub、OpenLineage 都支持自动化血缘采集。 +::: + +--- + +## 4. 元数据管理："描述数据的数据" + +元数据（Metadata）是关于数据的数据。如果数据是一本书的内容，元数据就是书的目录、作者、出版日期、ISBN 号。没有元数据，数据就是一堆无法理解的数字和字符串。 + +| 元数据类型 | 描述 | 示例 | +|-----------|------|------| +| 技术元数据 | 数据的物理存储信息 | 表名、字段类型、分区方式、存储位置 | +| 业务元数据 | 数据的业务含义 | 字段中文名、业务定义、计算口径 | +| 操作元数据 | 数据的运行状态 | ETL 执行时间、数据量、更新频率 | + +::: tip 数据字典的重要性 +数据字典是元数据管理最基础的产出。一个好的数据字典应该包含： +- **字段名**：英文名和中文名 +- **数据类型**：VARCHAR(50)、INT、DATETIME 等 +- **业务定义**：这个字段代表什么？怎么计算的？ +- **取值范围**：有效值是什么？空值是否允许？ +- **负责人**：谁维护这个字段？有问题找谁？ + +没有数据字典的团队，新人入职后理解一张表的含义可能需要一周；有数据字典的团队，10 分钟就够了。 +::: + +--- + +## 5. 数据分层架构：ODS → DWD → DWS → ADS + +数据仓库不是把所有数据堆在一起，而是按照**加工程度**分层存储。每一层有明确的职责，上层依赖下层，逐步从原始数据提炼为业务可用的数据。 + +| 层级 | 全称 | 职责 | 数据特点 | +|------|------|------|---------| +| ODS | 操作数据层 | 原样同步业务数据库 | 最原始，未经处理 | +| DWD | 明细数据层 | 清洗、标准化、去重 | 干净的明细记录 | +| DWS | 汇总数据层 | 按主题聚合（日/周/月） | 预计算的聚合指标 | +| ADS | 应用数据层 | 面向具体报表/接口 | 直接可用的结果数据 | + +::: tip 为什么要分层？ +- **复用**：DWD 层清洗一次，所有上层共享，避免重复清洗 +- **解耦**：业务库表结构变更只影响 ODS 层，不会波及报表 +- **性能**：DWS 层预聚合，报表查询直接读取，不需要实时计算 +- **可追溯**：每一层都保留，出问题时可以逐层排查 +::: + +--- + +## 6. 治理工具与实践 + +| 工具 | 定位 | 核心能力 | 适用场景 | +|------|------|---------|---------| +| Great Expectations | 数据质量 | 声明式数据校验规则，自动生成质量报告 | Python 数据管道 | +| dbt | 数据转换 | SQL 模型化开发，内置测试和文档生成 | 数仓建模 | +| DataHub | 元数据管理 | 数据目录、血缘追踪、数据发现 | 企业级数据治理 | +| Apache Atlas | 元数据管理 | Hadoop 生态血缘追踪 | 大数据平台 | +| OpenMetadata | 元数据管理 | 开源数据目录，支持多种数据源 | 中小团队 | +| Amundsen | 数据发现 | 搜索式数据发现平台 | 数据民主化 | + +::: tip 从零开始的治理路径 +如果你的团队还没有数据治理，建议按这个顺序推进： +1. **先建数据字典**：把现有的表和字段含义记录下来（哪怕用 Excel） +2. **加质量检查**：在关键数据管道中加入基本的空值、范围校验 +3. **统一指标定义**：把"日活""月活""GMV"等核心指标的计算口径统一 +4. **引入工具**：当手动管理成本太高时，引入 DataHub 或 dbt 等工具 +5. **建立流程**：数据变更需要评审，质量问题有 SLA 和告警 +::: + +--- + +## 总结 + +数据治理是让数据从"能用"变成"好用、可信、可追溯"的系统性工程。它不是一次性项目，而是持续运营的过程。 + +回顾本章的关键要点： + +1. **六大质量维度**：完整性、准确性、一致性、时效性、唯一性、有效性 +2. **治理四支柱**：组织、流程、技术、文化缺一不可 +3. **数据血缘**：追踪数据的来龙去脉，支撑影响分析和问题排查 +4. **元数据管理**：数据字典是最基础也最重要的治理产出 +5. **分层架构**：ODS → DWD → DWS → ADS，逐层提炼数据价值 +6. **渐进式落地**：从数据字典开始，逐步引入工具和流程 + +## 延伸阅读 + +- [DAMA-DMBOK](https://www.dama.org/cpages/body-of-knowledge) - 数据管理知识体系，数据治理的"圣经" +- [DataHub](https://datahubproject.io/) - LinkedIn 开源的元数据管理平台 +- [Great Expectations](https://greatexpectations.io/) - Python 数据质量框架 +- [dbt](https://www.getdbt.com/) - 数据转换工具，内置测试和文档 +- [Apache Atlas](https://atlas.apache.org/) - Hadoop 生态的元数据治理框架 +- [The Data Warehouse Toolkit](https://www.kimballgroup.com/data-warehouse-business-intelligence-resources/books/) - Kimball 数仓建模经典 diff --git a/docs/zh-cn/appendix/5-data/data-visualization.md b/docs/zh-cn/appendix/5-data/data-visualization.md index fbd64b1..8f1a7a0 100644 --- a/docs/zh-cn/appendix/5-data/data-visualization.md +++ b/docs/zh-cn/appendix/5-data/data-visualization.md @@ -1,3 +1,299 @@ # 数据可视化与仪表盘 -> 待实现 +::: tip 前言 +**一张好的图表胜过一千行数据。** 数据可视化是将抽象的数字转化为直观的视觉表达，让人能在几秒内理解数据背后的故事。从 Excel 图表到 Grafana 监控大屏，可视化无处不在。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **图表选择**：根据数据目的选择最合适的图表类型 +- **可视化原则**：掌握数据可视化的核心设计原则 +- **仪表盘设计**：了解不同类型仪表盘的布局模式 +- **工具生态**：熟悉主流可视化工具的定位和选型 +- **常见陷阱**：避免误导性图表和常见的可视化错误 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 图表类型选择 | 比较、趋势、占比、分布、关系 | +| **第 2 章** | 可视化设计原则 | 数据墨水比、一致性、可读性 | +| **第 3 章** | 仪表盘布局 | 概览型、对比型、下钻型、实时型 | +| **第 4 章** | 工具选型 | ECharts、D3、Grafana、Metabase | +| **第 5 章** | 常见陷阱 | 截断坐标轴、3D 饼图、颜色滥用 | + +--- + +## 0. 全景图：为什么需要可视化？ + +人类大脑处理视觉信息的速度比处理文字快 6 万倍。一张折线图能让你在 1 秒内看出"上个月销售额在下降"，而同样的信息如果用表格呈现，你可能需要 30 秒才能得出结论。 + +可视化的核心价值： + +- **发现模式**：趋势、周期、异常值在图表中一目了然 +- **辅助决策**：让非技术人员也能理解数据，参与决策 +- **沟通效率**：一图胜千言，减少数据解读的歧义 + +::: tip 可视化 ≠ 好看 +可视化的目标是**传达信息**，不是炫技。一个朴素但准确的柱状图，远比一个花哨但难以理解的 3D 图表更有价值。 +::: + +--- + +## 1. 图表类型选择：用对图表讲对故事 + +选择图表的第一步不是"我喜欢什么图表"，而是"我想传达什么信息"。不同的数据目的对应不同的最佳图表类型。 + + + +### 图表选择速查表 + +| 数据目的 | 推荐图表 | 不推荐 | 原因 | +|---------|---------|--------|------| +| 比较大小 | 柱状图、条形图 | 饼图 | 人眼对长度差异比角度差异更敏感 | +| 展示趋势 | 折线图、面积图 | 柱状图 | 折线的连续性暗示时间的连续性 | +| 展示占比 | 饼图（≤5 类）、堆叠柱状图 | 3D 饼图 | 3D 透视会扭曲面积比例 | +| 展示分布 | 直方图、箱线图 | 折线图 | 分布需要看频率，不是趋势 | +| 展示关系 | 散点图、气泡图 | 柱状图 | 两个连续变量的关系需要二维空间 | + +::: tip 一个简单的决策规则 +- **一个变量** → 直方图（分布）或数字卡片（KPI） +- **两个变量** → 折线图（时间 vs 数值）或散点图（数值 vs 数值） +- **多个类别** → 柱状图（比较）或饼图（占比，≤5 类） +- **多维度** → 雷达图或平行坐标图 +::: + +--- + +## 2. 可视化设计原则 + +Edward Tufte 在《The Visual Display of Quantitative Information》中提出了数据可视化的核心原则，至今仍是行业标准。 + +| 原则 | 说明 | 反面案例 | +|------|------|---------| +| 数据墨水比 | 图表中用于展示数据的"墨水"占比应尽量高 | 过多的网格线、装饰性元素 | +| 最小化非数据元素 | 去除不传达信息的视觉元素 | 3D 效果、阴影、渐变背景 | +| 一致的比例尺 | 坐标轴从零开始，刻度均匀 | Y 轴从 95 开始（夸大差异） | +| 合理的颜色使用 | 用颜色编码信息，而非装饰 | 彩虹色（无序）表示有序数据 | +| 清晰的标注 | 标题、轴标签、图例缺一不可 | 没有单位、没有时间范围 | + +::: tip 颜色使用的三条规则 +1. **同一指标用同一颜色**：收入在所有图表中都用蓝色，不要一会蓝一会绿 +2. **有序数据用渐变色**：温度从低到高用蓝→红渐变，不要用离散色 +3. **考虑色盲友好**：约 8% 的男性有红绿色盲，避免仅用红绿区分关键信息 +::: + +--- + +## 2. 可视化设计原则：让数据说话 + +好的可视化不是"好看"，而是"好懂"。Edward Tufte 在《The Visual Display of Quantitative Information》中提出了几个经典原则，至今仍是可视化设计的黄金标准。 + +### 2.1 数据墨水比（Data-Ink Ratio） + +> 图表中用于表达数据的"墨水"占总"墨水"的比例应该尽可能高。 + +简单说：**删掉一切不传达信息的元素**。 + +| 应该删掉的 | 应该保留的 | +|-----------|-----------| +| 3D 效果、阴影、渐变 | 数据点、坐标轴标签 | +| 多余的网格线 | 关键参考线（如目标值） | +| 装饰性图标 | 图例（当有多系列时） | +| 花哨的背景色 | 清晰的标题和单位 | + +### 2.2 一致性原则 + +- **颜色一致**：同一个维度在不同图表中用同一种颜色（如"收入"始终用蓝色） +- **比例一致**：坐标轴从 0 开始（除非有充分理由），避免误导 +- **时间一致**：时间轴的间隔应该均匀，不要跳跃 + +### 2.3 可读性原则 + +- **标题要说结论**：不是"月度销售额"，而是"销售额连续 3 个月下降" +- **标注关键点**：在异常值、拐点处加标注，引导读者注意力 +- **控制信息密度**：一张图表传达 1-2 个核心信息，不要塞太多 + +::: tip Tufte 的名言 +"Excellence in statistical graphics consists of complex ideas communicated with clarity, precision, and efficiency."（优秀的统计图形，是用清晰、精确、高效的方式传达复杂的想法。） +::: + +--- + +## 3. 仪表盘布局：不同场景，不同模式 + +仪表盘（Dashboard）是多个图表的有机组合。好的仪表盘不是把图表堆在一起，而是根据使用场景选择合适的布局模式。 + + + +### 四种常见布局模式 + +| 布局模式 | 核心结构 | 适用场景 | 设计要点 | +|---------|---------|---------|---------| +| 全局概览型 | KPI 卡片 + 趋势图 + 明细表 | 管理层日报、运营大盘 | 核心指标放最上方，一眼看到关键数字 | +| 对比分析型 | 左右对称布局 | A/B 测试、同环比分析 | 保持对比维度一致，突出差异 | +| 下钻分析型 | 从汇总到明细逐层展开 | 销售分析、用户行为分析 | 支持点击交互，逐层深入 | +| 实时监控型 | 大数字 + 实时曲线 + 告警状态 | 双十一大屏、服务器监控 | 自动刷新，深色背景，适合投屏 | + +### 仪表盘设计的 5 个原则 + +1. **先问"谁在看"**：CEO 看战略指标，运营看过程指标，工程师看技术指标 +2. **5 秒规则**：用户应该在 5 秒内理解仪表盘的核心信息 +3. **信息层次**：最重要的放左上角（F 型阅读模式），次要的放下方 +4. **减少滚动**：一屏展示核心内容，避免用户需要滚动才能看到关键数据 +5. **留白**：不要塞满每一寸空间，适当留白让视觉更舒适 + +::: tip 仪表盘 vs 报表 +- **仪表盘**：实时/准实时，交互式，面向监控和快速决策 +- **报表**：定期生成（日/周/月），静态，面向详细分析和存档 + +两者不是替代关系，而是互补关系。仪表盘发现问题，报表深入分析。 +::: + +--- + +## 4. 工具选型：从代码到拖拽 + +| 工具 | 类型 | 特点 | 适用场景 | +|------|------|------|---------| +| ECharts | JS 图表库 | 百度开源，图表类型丰富，中文文档完善 | 前端项目内嵌图表 | +| D3.js | JS 可视化库 | 底层灵活，可定制任意可视化效果 | 高度定制化需求 | +| Chart.js | JS 图表库 | 轻量简单，上手快 | 简单图表需求 | +| Grafana | 监控仪表盘 | 支持多数据源，实时刷新，告警集成 | 服务器/应用监控 | +| Metabase | BI 工具 | 开源，SQL 查询 + 拖拽建图 | 业务数据分析 | +| Superset | BI 工具 | Apache 开源，支持大数据源 | 企业级数据探索 | +| Tableau | 商业 BI | 拖拽式，交互能力强 | 企业级报表 | + +::: tip 怎么选？ +- **开发者做项目内嵌图表** → ECharts（功能全）或 Chart.js（轻量） +- **需要高度定制的可视化** → D3.js（学习曲线陡但无限可能） +- **运维监控大屏** → Grafana（行业标准） +- **业务团队自助分析** → Metabase（简单）或 Superset（功能强） +::: + +--- + +## 4. 工具选型：从代码库到 BI 平台 + +可视化工具可以分为三个层次：底层绑定库、高层图表库、BI 平台。选择哪个取决于你的需求复杂度和团队技术能力。 + +### 4.1 代码级图表库 + +| 工具 | 语言/平台 | 特点 | 适用场景 | +|------|----------|------|---------| +| ECharts | JavaScript | 开箱即用，图表类型丰富，中文文档完善 | 业务系统内嵌图表 | +| D3.js | JavaScript | 底层灵活，可定制任何可视化效果 | 高度定制化的数据可视化 | +| Chart.js | JavaScript | 轻量简单，上手快 | 简单的图表需求 | +| Matplotlib | Python | 科学计算标准库，静态图表 | 数据分析、论文图表 | +| Plotly | Python/JS | 交互式图表，支持 3D | 数据探索、Jupyter Notebook | + +### 4.2 BI 平台（无代码/低代码） + +| 工具 | 定位 | 核心优势 | 适用团队 | +|------|------|---------|---------| +| Grafana | 监控可视化 | 时序数据支持好，告警集成 | 运维/SRE 团队 | +| Metabase | 轻量 BI | 开源免费，SQL 即可出图 | 中小团队快速搭建 | +| Apache Superset | 企业 BI | 开源，支持大数据源 | 有数据团队的公司 | +| Tableau | 商业 BI | 拖拽式操作，可视化效果好 | 业务分析师 | +| Power BI | 商业 BI | 与微软生态集成好 | 使用微软技术栈的企业 | + +::: tip 选型建议 +- **开发者做产品内嵌图表** → ECharts（中文生态好）或 Chart.js（简单场景） +- **数据分析师做探索分析** → Plotly + Jupyter 或 Metabase +- **运维监控大屏** → Grafana（事实标准） +- **业务团队自助分析** → Metabase（开源）或 Tableau（商业） +- **需要高度定制** → D3.js（学习曲线陡峭，但无所不能） +::: + +--- + +## 5. 常见陷阱：这些图表在骗你 + +数据可视化是一把双刃剑——用得好能揭示真相，用得不好会制造谎言。以下是最常见的可视化陷阱，每个数据从业者都应该能识别。 + +### 5.1 截断坐标轴 + +把 Y 轴的起点从 0 改成一个较大的数字，会让微小的差异看起来像巨大的变化。 + +| 场景 | 真实差异 | 视觉感受 | +|------|---------|---------| +| Y 轴从 0 开始 | A 产品 98 分，B 产品 95 分 | 差距很小 | +| Y 轴从 90 开始 | 同样的数据 | A 看起来是 B 的好几倍 | + +**什么时候可以截断？** 当数据的绝对值很大但变化很小时（如股价从 100 到 105），截断是合理的——但必须明确标注。 + +### 5.2 3D 饼图的透视陷阱 + +3D 透视会让靠近观察者的扇区看起来更大。一个 25% 的扇区在 3D 视角下可能看起来像 35%。 + +**解决方案**：永远不要用 3D 饼图。用普通饼图或环形图，或者干脆用柱状图。 + +### 5.3 颜色滥用 + +| 错误做法 | 正确做法 | +|---------|---------| +| 用红绿表示数据（色盲不友好） | 用蓝橙等色盲安全配色 | +| 每个类别用不同颜色（彩虹图） | 同一系列用同色系深浅变化 | +| 用颜色编码连续数据但不加图例 | 始终提供颜色图例和数值标注 | +| 背景色和数据色对比度不够 | 确保 WCAG AA 级对比度 | + +### 5.4 其他常见错误 + +| 陷阱 | 问题 | 修复 | +|------|------|------| +| 双 Y 轴 | 两个不相关的指标共享 X 轴，暗示因果关系 | 拆成两张图，或明确说明无因果 | +| 面积误导 | 用圆的半径而非面积表示数值 | 数值翻倍时面积翻倍，不是半径翻倍 | +| 时间轴不均匀 | 1月、3月、12月的间距一样 | 按实际时间比例排列 | +| 过多类别 | 饼图有 15 个扇区 | 超过 5 个类别就用柱状图或合并"其他" | + +::: tip 可视化的道德准则 +可视化的目的是**帮助理解**，不是**操纵认知**。每次做图表时问自己： +- 如果我是读者，这张图会不会让我产生错误的结论？ +- 我是否隐藏了不利的数据？ +- 坐标轴、比例、颜色是否公正地呈现了数据？ +::: + +--- + +## 总结 + +数据可视化是数据价值传递的"最后一公里"。选对图表、遵循设计原则、避免常见陷阱，就能让数据真正"说话"。 + +回顾本章的关键要点： + +1. **先问目的再选图表**：比较用柱状图、趋势用折线图、占比用饼图 +2. **数据墨水比**：删掉一切不传达信息的视觉元素 +3. **仪表盘有模式**：概览型、对比型、下钻型、实时型各有适用场景 +4. **工具按需选**：ECharts 做产品、Grafana 做监控、Metabase 做分析 +5. **警惕视觉陷阱**：截断坐标轴、3D 饼图、颜色滥用都会误导读者 + +## 延伸阅读 + +- [ECharts 官方文档](https://echarts.apache.org/zh/index.html) - 最流行的中文图表库 +- [D3.js](https://d3js.org/) - 数据驱动的可视化库 +- [Grafana](https://grafana.com/) - 开源监控可视化平台 +- [The Visual Display of Quantitative Information](https://www.edwardtufte.com/tufte/books_vdqi) - Tufte 的可视化经典 +- [From Data to Viz](https://www.data-to-viz.com/) - 图表类型选择指南 + +--- + +## 总结 + +数据可视化是数据价值传递的"最后一公里"。再好的分析，如果不能被正确理解，就等于没有分析。 + +回顾本章的关键要点： + +1. **选对图表**：根据数据目的（比较、趋势、占比、分布、关系）选择图表类型 +2. **设计原则**：高数据墨水比、一致性、可读性是三大核心原则 +3. **仪表盘布局**：概览型、对比型、下钻型、实时型四种模式覆盖大部分场景 +4. **工具选型**：从 ECharts 到 Grafana，根据团队能力和需求复杂度选择 +5. **避免陷阱**：截断坐标轴、3D 饼图、颜色滥用是最常见的误导手段 + +## 延伸阅读 + +- [The Visual Display of Quantitative Information](https://www.edwardtufte.com/tufte/books_vdqi) - Edward Tufte 的可视化经典 +- [ECharts 官方文档](https://echarts.apache.org/zh/index.html) - 最流行的中文图表库 +- [D3.js](https://d3js.org/) - 最强大的底层可视化库 +- [Grafana](https://grafana.com/) - 监控可视化事实标准 +- [From Data to Viz](https://www.data-to-viz.com/) - 图表类型选择决策树 +- [ColorBrewer](https://colorbrewer2.org/) - 色盲安全的配色方案工具 diff --git a/docs/zh-cn/appendix/6-architecture-and-system-design/distributed-systems.md b/docs/zh-cn/appendix/6-architecture-and-system-design/distributed-systems.md index 65018a8..35d0027 100644 --- a/docs/zh-cn/appendix/6-architecture-and-system-design/distributed-systems.md +++ b/docs/zh-cn/appendix/6-architecture-and-system-design/distributed-systems.md @@ -1,3 +1,253 @@ # 分布式系统的挑战 -> 待实现 +::: tip 前言 +**当一台机器不够用时，问题才真正开始。** 分布式系统是现代互联网的基石——从微信消息到淘宝下单，背后都是成百上千台机器协同工作。但"分布式"不是免费的午餐，它带来了一系列单机系统从未遇到的挑战。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **核心定理**：理解 CAP 定理及其对系统设计的影响 +- **一致性模型**：区分强一致性、最终一致性、因果一致性 +- **八大挑战**：掌握分布式系统面临的核心难题 +- **共识算法**：了解 Paxos、Raft 等分布式共识的基本思想 +- **实战模式**：熟悉 2PC、Saga、CRDT 等常用解决方案 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 为什么需要分布式 | 扩展性、可用性、地理分布 | +| **第 2 章** | CAP 定理 | 一致性、可用性、分区容错 | +| **第 3 章** | 一致性模型 | 强一致、最终一致、因果一致 | +| **第 4 章** | 八大挑战 | 网络、时钟、分区、脑裂等 | +| **第 5 章** | 共识算法 | Paxos、Raft、ZAB | +| **第 6 章** | 分布式事务 | 2PC、Saga、TCC | + +--- + +## 0. 全景图：为什么需要分布式系统？ + +单机系统简单可靠，但有三个无法逾越的瓶颈： + +| 瓶颈 | 说明 | 分布式的解法 | +|------|------|-------------| +| 性能上限 | 单机 CPU、内存、磁盘有物理极限 | 水平扩展：加更多机器分担负载 | +| 单点故障 | 一台机器挂了，整个服务就挂了 | 冗余副本：多台机器互为备份 | +| 地理延迟 | 用户在全球各地，单机只能在一个地方 | 多地部署：就近服务用户 | + +::: tip 分布式的代价 +分布式系统解决了上面的问题，但引入了新的复杂性：网络不可靠、时钟不同步、部分失败、数据一致性……这些就是本文要讨论的"挑战"。 + +**Peter Deutsch 的分布式计算八大谬误**告诉我们，以下假设在分布式环境中都是错的： +1. 网络是可靠的 +2. 延迟是零 +3. 带宽是无限的 +4. 网络是安全的 +5. 拓扑不会变化 +6. 只有一个管理员 +7. 传输成本是零 +8. 网络是同构的 +::: + +--- + +## 1. CAP 定理：分布式系统的"不可能三角" + +2000 年，Eric Brewer 提出了 CAP 猜想（后被证明为定理）：一个分布式系统最多只能同时满足以下三个属性中的两个。 + +| 属性 | 含义 | 通俗理解 | +|------|------|---------| +| **C**onsistency（一致性） | 所有节点在同一时刻看到相同的数据 | 你在任何 ATM 查余额，结果都一样 | +| **A**vailability（可用性） | 每个请求都能收到非错误的响应 | 系统永远能回应你，不会说"服务不可用" | +| **P**artition tolerance（分区容错） | 网络分区时系统仍能继续运行 | 即使部分网线断了，系统还能工作 | + + + +### 为什么只能选两个？ + +在分布式环境中，网络分区（P）是不可避免的——光纤会被挖断、交换机会故障、数据中心会断网。所以 P 是必选项，实际的选择是在 C 和 A 之间权衡： + +- **选 CP**：分区时拒绝不确定的请求，保证数据正确 → 适合金融、库存 +- **选 AP**：分区时继续服务，但数据可能暂时不一致 → 适合社交、内容 + +::: tip CAP 不是非黑即白 +现实中的系统不是简单的"CP 或 AP"。很多系统在不同操作上做不同的选择——比如同一个数据库，读操作可以是 AP（允许读旧数据），写操作可以是 CP（要求多数确认）。 +::: + +--- + +## 2. 一致性模型：数据同步的"严格程度" + +一致性不是一个开关（有或没有），而是一个光谱。不同的一致性模型在"正确性"和"性能"之间做不同的权衡。 + + + +### 一致性模型对比 + +| 模型 | 保证 | 延迟 | 适用场景 | +|------|------|------|---------| +| 强一致性 | 读到的一定是最新写入的值 | 高（需等待同步） | 银行转账、库存扣减 | +| 最终一致性 | 最终所有副本会一致，但中间可能读到旧值 | 低（写入立即返回） | 社交动态、DNS | +| 因果一致性 | 有因果关系的操作保证顺序 | 中等 | 评论回复、协作编辑 | +| 线性一致性 | 所有操作看起来像在单机上按顺序执行 | 最高 | 分布式锁、选主 | +| 会话一致性 | 同一会话内保证读到自己的写入 | 低-中 | 用户个人数据 | + +::: tip "读己之写"一致性 +最常见的实际需求是：用户修改了自己的数据后，自己能立即看到更新（但其他用户可以稍后看到）。这叫"Read Your Own Writes"一致性，是最终一致性的一个实用增强。 +::: + +--- + +## 3. 八大挑战：分布式系统的"地雷阵" + +分布式系统的复杂性不是来自某一个问题，而是多个问题交织在一起。以下是最核心的八大挑战。 + + + +### 挑战之间的关联 + +这八大挑战不是孤立的，它们相互关联： + +- **网络不可靠** → 导致 **网络分区** → 触发 **CAP 权衡** +- **时钟不同步** → 导致 **事件排序困难** → 影响 **数据一致性** +- **部分失败** → 可能导致 **脑裂** → 需要 **共识算法** 来解决 +- **数据一致性** → 需要 **分布式事务** → 但事务又受 **网络不可靠** 影响 + +::: tip 没有银弹 +分布式系统没有"完美"的解决方案，只有"合适"的权衡。理解这些挑战的本质，才能在设计系统时做出正确的取舍。 +::: + +--- + +## 4. 共识算法：如何让多台机器"达成一致" + +共识算法是分布式系统的核心——它解决的问题是：多个节点如何就某个值达成一致？即使部分节点故障或网络延迟。 + +### 4.1 Paxos + +Leslie Lamport 在 1990 年提出，是第一个被严格证明正确的共识算法。 + +| 角色 | 职责 | +|------|------| +| Proposer | 提出提案（值） | +| Acceptor | 投票接受或拒绝提案 | +| Learner | 学习最终被选定的值 | + +**两阶段流程**： +1. **Prepare 阶段**：Proposer 发送提案编号，Acceptor 承诺不再接受更小编号的提案 +2. **Accept 阶段**：Proposer 发送具体值，多数 Acceptor 接受则提案通过 + +::: tip Paxos 的问题 +Paxos 虽然正确，但出了名的难以理解和实现。Lamport 自己的论文用了一个希腊议会的比喻，结果让更多人困惑了。 +::: + +### 4.2 Raft：为可理解性而生 + +2014 年 Diego Ongaro 提出 Raft，目标是做一个"容易理解的 Paxos"。它把共识问题分解为三个子问题： + +| 子问题 | 说明 | +|--------|------| +| Leader 选举 | 集群中选出一个 Leader，所有写入都经过 Leader | +| 日志复制 | Leader 将操作日志复制到所有 Follower | +| 安全性 | 保证已提交的日志不会被覆盖 | + +**Raft 的核心流程**： +1. 集群启动时，所有节点都是 Follower +2. 如果 Follower 超时没收到 Leader 心跳，就变成 Candidate 发起选举 +3. 获得多数票的 Candidate 成为新 Leader +4. Leader 接收客户端请求，将日志复制到多数节点后提交 + +### 4.3 共识算法对比 + +| 算法 | 提出时间 | 可理解性 | 使用系统 | +|------|---------|---------|---------| +| Paxos | 1990 | 困难 | Google Chubby | +| Raft | 2014 | 容易 | etcd、Consul、TiKV | +| ZAB | 2011 | 中等 | ZooKeeper | +| EPaxos | 2013 | 困难 | 学术研究为主 | + +--- + +## 5. 分布式事务：跨节点的"全有或全无" + +单机数据库的事务靠本地锁和日志就能实现 ACID。但当一个业务操作涉及多个服务/数据库时，如何保证原子性？ + +### 5.1 两阶段提交（2PC） + +最经典的分布式事务协议，分为两个阶段： + +| 阶段 | 协调者动作 | 参与者动作 | +|------|-----------|-----------| +| Prepare | 问所有参与者"能提交吗？" | 执行操作但不提交，回复 Yes/No | +| Commit | 如果全部 Yes，发送 Commit | 正式提交；如果有 No，全部回滚 | + +**2PC 的问题**： +- **阻塞**：Prepare 后如果协调者挂了，参与者会一直等待 +- **单点故障**：协调者是单点，挂了整个事务卡住 +- **性能差**：需要多次网络往返，锁持有时间长 + +### 5.2 Saga 模式 + +Saga 把一个大事务拆成多个本地事务，每个本地事务有对应的补偿操作。如果某一步失败，就逆序执行补偿。 + +**电商下单的 Saga 示例**： + +| 步骤 | 正向操作 | 补偿操作 | +|------|---------|---------| +| T1 | 创建订单（待支付） | 取消订单 | +| T2 | 扣减库存 | 恢复库存 | +| T3 | 扣减余额 | 退还余额 | +| T4 | 确认订单（已支付） | — | + +如果 T3（扣减余额）失败：执行 C2（恢复库存）→ C1（取消订单）。 + +**两种编排方式**： +- **编排式（Choreography）**：每个服务监听事件，自行决定下一步。简单但难以追踪全局状态 +- **协调式（Orchestration）**：有一个中心协调者控制流程。清晰但协调者是单点 + +### 5.3 TCC（Try-Confirm-Cancel） + +TCC 是 2PC 的业务层实现，把每个操作分为三个阶段： + +| 阶段 | 说明 | 示例（扣库存） | +|------|------|---------------| +| Try | 预留资源，但不真正执行 | 冻结 10 件库存（可用库存 -10，冻结库存 +10） | +| Confirm | 确认执行，消耗预留资源 | 冻结库存 -10（真正扣减） | +| Cancel | 取消预留，释放资源 | 冻结库存 -10，可用库存 +10（恢复） | + +### 5.4 三种方案对比 + +| 方案 | 一致性 | 性能 | 复杂度 | 适用场景 | +|------|--------|------|--------|---------| +| 2PC | 强一致 | 低 | 中 | 数据库层面的跨库事务 | +| Saga | 最终一致 | 高 | 高 | 长流程业务（订单、物流） | +| TCC | 最终一致 | 中 | 最高 | 资金类高可靠场景 | + +::: tip 实际选择建议 +- 能用单库事务就不要用分布式事务 +- 大多数业务场景用 Saga + 消息队列就够了 +- TCC 适合对一致性要求极高的金融场景，但开发成本很高 +- 2PC 适合数据库中间件（如 ShardingSphere）自动处理 +::: + +--- + +## 总结 + +分布式系统是现代互联网的基础设施，但它的复杂性远超单机系统。理解这些挑战不是为了"解决"它们（很多是根本性的），而是为了在设计系统时做出正确的权衡。 + +回顾本章的关键要点： + +1. **CAP 定理**：网络分区不可避免，实际选择是在一致性和可用性之间权衡 +2. **一致性模型**：从强一致到最终一致是一个光谱，根据业务需求选择 +3. **八大挑战**：网络不可靠、时钟不同步、网络分区、脑裂等相互关联 +4. **共识算法**：Raft 是目前最实用的共识算法，etcd/Consul 都基于它 +5. **分布式事务**：Saga 适合大多数场景，TCC 适合金融场景，2PC 适合数据库层 + +## 延伸阅读 + +- [Designing Data-Intensive Applications](https://dataintensive.net/) - Martin Kleppmann 的分布式系统经典 +- [The Raft Consensus Algorithm](https://raft.github.io/) - Raft 官方可视化演示 +- [CAP Twelve Years Later](https://www.infoq.com/articles/cap-twelve-years-later-how-the-rules-have-changed/) - Brewer 对 CAP 的重新审视 +- [Jepsen](https://jepsen.io/) - 分布式系统正确性测试框架 +- [分布式系统模式](https://martinfowler.com/articles/patterns-of-distributed-systems/) - Martin Fowler 的分布式模式合集 \ No newline at end of file diff --git a/docs/zh-cn/appendix/6-architecture-and-system-design/high-availability.md b/docs/zh-cn/appendix/6-architecture-and-system-design/high-availability.md index f1527e6..15f832e 100644 --- a/docs/zh-cn/appendix/6-architecture-and-system-design/high-availability.md +++ b/docs/zh-cn/appendix/6-architecture-and-system-design/high-availability.md @@ -1,3 +1,204 @@ # 高可用与容灾 -> 待实现 +::: tip 前言 +**系统挂了 1 分钟，可能意味着几十万的损失。** 高可用（High Availability）是指系统在面对硬件故障、软件 Bug、网络问题等异常情况时，仍能持续提供服务的能力。容灾（Disaster Recovery）则是在更大范围的灾难发生时，系统能够恢复服务的能力。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **可用性度量**：理解"几个 9"的含义和对应的停机时间 +- **故障转移**：掌握主备、主主、多活等高可用架构 +- **容灾策略**：了解 RPO 和 RTO 的概念及设计方法 +- **故障检测**：理解心跳、探针、熔断等故障发现机制 +- **混沌工程**：了解如何主动注入故障来验证系统韧性 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 可用性度量 | SLA、几个 9、停机时间 | +| **第 2 章** | 故障转移架构 | 主备、主主、多可用区、异地多活 | +| **第 3 章** | 容灾设计 | RPO、RTO、备份策略 | +| **第 4 章** | 故障检测与恢复 | 心跳、熔断、自动扩缩容 | +| **第 5 章** | 混沌工程 | 故障注入、韧性验证 | + +--- + +## 1. 可用性度量：几个 9 意味着什么？ + +可用性通常用"几个 9"来衡量，计算公式为： + +**可用性 = 正常运行时间 / 总时间 × 100%** + +例如一个月（30 天 = 43200 分钟）内停机了 43 分钟，可用性就是 (43200 - 43) / 43200 ≈ 99.9%。每多一个 9，允许的停机时间就少一个数量级，实现难度和成本也指数级增长。 + +| 可用性等级 | 百分比 | 每月允许停机 | 每年允许停机 | 典型要求 | +|-----------|--------|------------|------------|---------| +| 2 个 9 | 99% | 7.3 小时 | 3.65 天 | 内部工具 | +| 3 个 9 | 99.9% | 43 分钟 | 8.76 小时 | 普通业务系统 | +| 4 个 9 | 99.99% | 4.3 分钟 | 52.6 分钟 | 电商、SaaS | +| 5 个 9 | 99.999% | 26 秒 | 5.26 分钟 | 金融、支付 | + + + +::: tip SLA 是什么？ +**SLA（Service Level Agreement，服务等级协议）** 是服务提供方与客户之间的正式承诺。比如 AWS S3 承诺 99.99% 的可用性，如果没达到，会按比例退款。SLA 不只是技术指标，更是商业合同——违反 SLA 意味着赔钱。 +::: + +::: tip 从 3 个 9 到 4 个 9 的鸿沟 +3 个 9（99.9%）意味着每月可以停机 43 分钟——一次部署出问题，回滚一下就用完了。 +4 个 9（99.99%）意味着每月只能停机 4 分钟——这要求你必须有自动故障转移、滚动部署、健康检查等完整的高可用体系。 +::: + +--- + +## 2. 故障转移架构 + +故障转移（Failover）是高可用的核心机制：当主节点故障时，自动切换到备用节点继续提供服务。 + +### 主备模式（Active-Standby） + +最常见的高可用架构。主节点处理所有请求，备节点实时同步数据但不处理请求。主节点故障时，备节点自动接管。 + +``` +正常状态： + 客户端 → 主节点（处理请求） + 备节点（同步数据，待命） + +故障转移： + 客户端 → 备节点（接管为新主节点） + 原主节点（故障，等待修复） +``` + +关键问题是**脑裂（Split Brain）**：网络分区时，主备节点都认为对方挂了，同时对外提供服务，导致数据不一致。解决方案是引入**仲裁节点（Quorum）**——至少 3 个节点投票决定谁是主节点。 + +### 多可用区（Multi-AZ） + +将服务部署在同一地域的多个数据中心（可用区）。单个数据中心断电、断网不影响整体服务。云厂商的可用区之间通常有低延迟专线连接（< 2ms）。 + +### 异地多活（Multi-Region Active-Active） + +在不同城市甚至不同国家部署完整的服务副本，每个站点都能独立处理请求。这是最高级别的高可用架构，但也最复杂——核心挑战是**跨地域数据同步**的延迟和一致性问题。 + + + +| 架构 | 可用性级别 | 成本 | 复杂度 | 适用场景 | +|------|-----------|------|--------|---------| +| 单机 | 99%~99.9% | 低 | 低 | 开发测试、内部工具 | +| 主备 | 99.9%~99.99% | 中 | 中 | 中小型业务系统 | +| 多可用区 | 99.99% | 高 | 高 | 电商、SaaS 平台 | +| 异地多活 | 99.999% | 极高 | 极高 | 金融、大型互联网 | + +--- + +## 3. 容灾设计：RPO 与 RTO + +容灾设计围绕两个核心指标展开： + +| 指标 | 全称 | 含义 | 举例 | +|------|------|------|------| +| RPO | Recovery Point Objective | 能容忍丢失多少数据 | RPO=0 表示不能丢任何数据 | +| RTO | Recovery Time Objective | 能容忍停机多长时间 | RTO=5min 表示 5 分钟内恢复 | + +### 备份策略与 RPO 的关系 + +| 备份方式 | RPO | 成本 | 说明 | +|---------|-----|------|------| +| 每日全量备份 | 24 小时 | 低 | 最多丢一天数据 | +| 实时增量备份 | 分钟级 | 中 | binlog/WAL 持续同步 | +| 同步复制 | 0 | 高 | 写入必须等副本确认 | + +::: tip 不是所有数据都需要 RPO=0 +用户头像丢了可以重新上传（RPO=24h 够了），但支付记录一条都不能丢（RPO=0）。根据数据的业务价值来决定备份策略，而不是一刀切。 +::: + +--- + +## 4. 故障检测与恢复 + +### 4.1 故障检测机制 + +| 机制 | 原理 | 检测速度 | 适用场景 | +|------|------|---------|---------| +| 心跳检测 | 定期发送心跳包，超时判定故障 | 秒级 | 节点存活检测 | +| 健康检查 | HTTP/TCP 探针检查服务状态 | 秒级 | 负载均衡器后端检测 | +| 业务探针 | 模拟真实请求检查业务逻辑 | 秒~分钟级 | 端到端可用性监控 | + +**心跳检测的工作原理**：节点 A 每隔固定时间（如 5 秒）向监控方发送一个"我还活着"的信号。如果连续 N 次（如 3 次）没收到心跳，就判定节点 A 故障。关键参数是**心跳间隔**和**超时阈值**——间隔太短会增加网络开销，太长会延迟故障发现。 + +**健康检查的三种级别**： +- **存活探针（Liveness）**：进程还在运行吗？不在就重启 +- **就绪探针（Readiness）**：服务能接受请求吗？不能就从负载均衡中摘除 +- **启动探针（Startup）**：服务启动完成了吗？没完成就等待，不要误判为故障 + +### 4.2 自动恢复机制 + +| 机制 | 描述 | 典型工具 | +|------|------|---------| +| 自动重启 | 进程崩溃后自动拉起 | systemd、PM2、K8s | +| 自动扩缩容 | 负载升高时自动增加实例 | K8s HPA、云厂商 Auto Scaling | +| 熔断降级 | 下游故障时快速失败，防止级联故障 | Hystrix、Sentinel、Resilience4j | +| 限流 | 超过容量的请求直接拒绝 | Nginx limit_req、网关限流 | + +**熔断器模式（Circuit Breaker）详解**： + +熔断器的灵感来自电路中的保险丝——当电流过大时自动断开，保护整个电路不被烧毁。在微服务中，当下游服务故障时，熔断器会"断开"，让请求快速失败，而不是傻等超时。 + +``` +熔断器三种状态： + + 关闭（正常）──→ 失败率超过阈值 ──→ 打开（熔断） + ↑ │ + │ 等待冷却时间 + │ ↓ + └── 探测请求成功 ←── 半开（试探） +``` + +- **关闭状态**：正常转发请求，同时统计失败率 +- **打开状态**：所有请求直接返回错误（快速失败），不再调用下游 +- **半开状态**：冷却时间到后，放行少量探测请求。如果成功，恢复关闭；如果失败，继续打开 + +**降级（Fallback）** 是熔断的配套策略：熔断触发后，不是直接报错，而是返回一个"兜底"结果。比如推荐服务挂了，就返回热门商品列表；用户头像加载失败，就显示默认头像。 + +--- + +## 5. 混沌工程：主动找问题 + +混沌工程的核心理念是：**与其等故障发生，不如主动制造故障**，在可控环境中验证系统的韧性。 + +| 工具 | 提出者 | 核心能力 | +|------|--------|---------| +| Chaos Monkey | Netflix | 随机终止生产环境的实例 | +| Chaos Mesh | PingCAP | K8s 环境下的故障注入 | +| Litmus | CNCF | 云原生混沌工程框架 | +| ChaosBlade | 阿里巴巴 | 多场景故障注入工具 | + +::: tip 混沌工程的实施步骤 +1. **定义稳态**：明确系统正常运行的指标（如 P99 延迟 < 200ms） +2. **提出假设**：如果某个节点挂了，系统应该在 30 秒内自动恢复 +3. **注入故障**：在可控范围内制造故障（先在测试环境，再到生产） +4. **观察结果**：系统是否如预期恢复？有没有级联故障？ +5. **修复弱点**：发现问题后改进架构和流程 +::: + +--- + +## 总结 + +高可用不是一个功能，而是一种架构能力。它需要从设计、开发、部署、运维的每个环节去保障。 + +回顾本章的关键要点： + +1. **几个 9**：每多一个 9，停机时间少一个数量级，成本和复杂度指数增长 +2. **故障转移**：从主备到异地多活，根据业务需求选择合适的架构 +3. **RPO 与 RTO**：根据数据价值和业务容忍度设计备份和恢复策略 +4. **自动化**：故障检测、自动重启、熔断降级是高可用的基础设施 +5. **混沌工程**：主动制造故障，在可控环境中验证系统韧性 + +## 延伸阅读 + +- [Site Reliability Engineering](https://sre.google/sre-book/table-of-contents/) - Google SRE 经典 +- [Chaos Monkey](https://netflix.github.io/chaosmonkey/) - Netflix 混沌工程工具 +- [Release It!](https://pragprog.com/titles/mnee2/release-it-second-edition/) - 生产环境设计模式 +- [Chaos Mesh](https://chaos-mesh.org/) - K8s 混沌工程平台 + diff --git a/docs/zh-cn/appendix/6-architecture-and-system-design/monolith-to-microservices.md b/docs/zh-cn/appendix/6-architecture-and-system-design/monolith-to-microservices.md index 28bce8b..e40f8ef 100644 --- a/docs/zh-cn/appendix/6-architecture-and-system-design/monolith-to-microservices.md +++ b/docs/zh-cn/appendix/6-architecture-and-system-design/monolith-to-microservices.md @@ -1,3 +1,156 @@ # 从单体到微服务的演进 -> 待实现 +::: tip 前言 +**没有哪个架构是"最好的"，只有"最适合当前阶段的"。** 从单体到微服务不是一步到位的跳跃，而是随着业务规模和团队规模增长，逐步演进的过程。过早拆分微服务和过晚拆分一样危险。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **演进路径**：理解从单体到微服务的四个阶段 +- **拆分时机**：知道什么时候该拆、什么时候不该拆 +- **拆分策略**：掌握按业务域拆分的方法论 +- **通信模式**：了解服务间同步和异步通信的选择 +- **数据拆分**：理解数据库拆分的挑战和方案 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 架构演进路径 | 单体→模块化→SOA→微服务 | +| **第 2 章** | 拆分时机与原则 | Conway 定律、团队自治 | +| **第 3 章** | 拆分策略 | DDD 限界上下文、绞杀者模式 | +| **第 4 章** | 服务通信 | REST、gRPC、消息队列 | +| **第 5 章** | 数据拆分 | 数据库拆分、数据同步 | + +--- + +## 1. 架构演进路径 + +架构演进不是技术驱动的，而是**组织规模驱动的**。当团队从 5 人增长到 500 人时，单体架构的协作效率会急剧下降。 + +| 阶段 | 架构 | 团队规模 | 特点 | +|------|------|---------|------| +| 起步期 | 单体应用 | 1~10 人 | 所有代码在一个项目中，部署简单 | +| 成长期 | 模块化单体 | 10~50 人 | 代码按模块划分，但仍然一起部署 | +| 扩张期 | SOA（面向服务） | 50~200 人 | 按业务线拆分为粗粒度服务 | +| 规模期 | 微服务 | 200+ 人 | 细粒度服务，每个团队独立开发部署 | + + + +::: tip Conway 定律 +"设计系统的组织，其产生的架构等同于组织的沟通结构。"——Melvin Conway + +简单说：3 个团队做一个系统，最终会变成 3 个服务。架构拆分的本质是**组织拆分**。 + +**反向 Conway 定律**：既然组织结构决定了系统架构，那么想要什么样的架构，就先调整成什么样的组织结构。比如你想拆出独立的支付服务，就先组建一个独立的支付团队。很多公司微服务拆分失败，不是技术问题，而是组织没有跟着调整。 +::: + +--- + +## 2. 什么时候该拆微服务？ + +不是所有系统都需要微服务。过早拆分会带来不必要的复杂性。 + +| 信号 | 说明 | 建议 | +|------|------|------| +| 部署冲突频繁 | 多个团队改同一个代码库，经常冲突 | 考虑拆分 | +| 某模块需要独立扩容 | 搜索模块需要 10 倍于其他模块的资源 | 考虑拆分 | +| 技术栈需要差异化 | AI 模块用 Python，主站用 Java | 考虑拆分 | +| 团队 < 10 人 | 沟通成本低，单体足够 | 不要拆 | +| 业务还在探索期 | 需求变化快，边界不清晰 | 不要拆 | +| 没有 DevOps 能力 | 没有 CI/CD、容器化、监控体系 | 不要拆 | + +--- + +## 3. 拆分策略 + +### 3.1 按业务域拆分（DDD 限界上下文） + +DDD（领域驱动设计）的限界上下文（Bounded Context）是拆分微服务的最佳指导原则。每个限界上下文对应一个独立的业务域，有自己的数据模型和业务规则。 + +**什么是限界上下文？** 同一个词在不同业务域中含义不同。比如"用户"在用户域是指注册信息（姓名、邮箱），在订单域是指下单人（收货地址、支付方式），在推荐域是指行为画像（浏览历史、偏好标签）。限界上下文就是划定一个边界，在这个边界内，术语和模型有明确统一的含义。 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 用户域 │ │ 订单域 │ │ 支付域 │ +│ │ │ │ │ │ +│ User │ │ Order │ │ Payment │ +│ Profile │ │ OrderItem │ │ Refund │ +│ Address │ │ Cart │ │ Transaction │ +│ │ │ │ │ │ +│ 用户服务 │ │ 订单服务 │ │ 支付服务 │ +└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + └────── API 调用 / 事件通信 ───────┘ +``` + +| 限界上下文 | 核心实体 | 对应服务 | +|-----------|---------|---------| +| 用户域 | User、Profile、Address | 用户服务 | +| 商品域 | Product、Category、SKU | 商品服务 | +| 订单域 | Order、OrderItem | 订单服务 | +| 支付域 | Payment、Refund | 支付服务 | +| 物流域 | Shipment、Tracking | 物流服务 | + +### 3.2 绞杀者模式（Strangler Fig Pattern） + +不要一次性重写整个单体，而是像绞杀榕一样，逐步用新服务替换旧模块： + +1. 在单体外部创建新服务 +2. 通过代理层将部分流量路由到新服务 +3. 验证新服务稳定后，逐步迁移更多流量 +4. 最终完全替换旧模块 + +--- + +## 4. 服务通信模式 + +| 方式 | 协议 | 特点 | 适用场景 | +|------|------|------|---------| +| REST | HTTP/JSON | 简单通用，生态好 | 对外 API、CRUD 操作 | +| gRPC | HTTP/2 + Protobuf | 高性能，强类型 | 内部服务间高频调用 | +| 消息队列 | AMQP/Kafka | 异步解耦，削峰填谷 | 事件通知、异步任务 | +| GraphQL | HTTP/JSON | 客户端按需查询 | BFF 层、移动端 | + +::: tip 同步 vs 异步的选择 +- **需要立即返回结果** → 同步（REST/gRPC） +- **不需要立即返回** → 异步（消息队列） +- **一个事件触发多个动作** → 异步（发布-订阅） + +经验法则：能异步就异步，同步调用链越长，系统越脆弱。 +::: + +--- + +## 5. 数据拆分：最难的部分 + +微服务拆分中最痛苦的不是代码拆分，而是数据库拆分。每个服务应该拥有自己的数据库，但这意味着跨服务查询变得困难。 + +| 挑战 | 描述 | 解决方案 | +|------|------|---------| +| 跨服务 JOIN | 不能直接 JOIN 两个服务的表 | API 组合查询、数据冗余 | +| 分布式事务 | 跨库事务无法用本地事务 | Saga、本地消息表 | +| 数据一致性 | 多个服务的数据可能暂时不一致 | 最终一致性、事件驱动 | +| 数据迁移 | 从共享库迁移到独立库 | 双写过渡、数据同步工具 | + +--- + +## 总结 + +从单体到微服务是一个渐进的过程，不是一蹴而就的革命。 + +回顾本章的关键要点： + +1. **演进路径**：单体→模块化单体→SOA→微服务，每一步都有明确的驱动力 +2. **拆分时机**：团队规模、部署冲突、扩容需求是拆分的信号 +3. **拆分策略**：用 DDD 限界上下文指导拆分，用绞杀者模式渐进迁移 +4. **通信选择**：能异步就异步，同步调用链越短越好 +5. **数据拆分**：最难但最重要，接受最终一致性是关键心态转变 + +## 延伸阅读 + +- [Building Microservices](https://www.oreilly.com/library/view/building-microservices-2nd/9781492034018/) - Sam Newman 微服务经典 +- [Monolith to Microservices](https://www.oreilly.com/library/view/monolith-to-microservices/9781492047834/) - 渐进式迁移指南 +- [Domain-Driven Design](https://www.domainlanguage.com/ddd/) - Eric Evans 的 DDD 经典 +- [The Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html) - Martin Fowler 的绞杀者模式 + diff --git a/docs/zh-cn/appendix/6-architecture-and-system-design/system-design-methodology.md b/docs/zh-cn/appendix/6-architecture-and-system-design/system-design-methodology.md index 2e8c469..169230d 100644 --- a/docs/zh-cn/appendix/6-architecture-and-system-design/system-design-methodology.md +++ b/docs/zh-cn/appendix/6-architecture-and-system-design/system-design-methodology.md @@ -1,3 +1,252 @@ # 系统设计方法论 -> 待实现 +::: tip 前言 +**系统设计不是拍脑袋画架构图，而是一套有章可循的方法论。** 无论是面试中的系统设计题，还是实际工作中的架构设计，都遵循相似的思考框架：先搞清楚问题，再估算规模，然后设计方案，最后深入优化。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **设计流程**：掌握系统设计的四步法框架 +- **容量估算**：学会"信封背面估算"的技巧 +- **常见模式**：熟悉缓存、分库分表、消息队列等核心模式 +- **权衡思维**：理解架构设计中的 trade-off 思维 +- **实战案例**：通过短链服务、Feed 流等案例理解设计过程 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 设计四步法 | 需求澄清、容量估算、架构设计、深入优化 | +| **第 2 章** | 容量估算 | QPS、存储、带宽、信封背面估算 | +| **第 3 章** | 核心设计模式 | 缓存、分库分表、消息队列、CDN | +| **第 4 章** | 权衡思维 | 一致性 vs 可用性、性能 vs 成本 | +| **第 5 章** | 经典案例 | 短链服务、Feed 流、秒杀系统 | + +--- + +## 1. 系统设计四步法 + +系统设计不是一上来就画架构图。无论是面试还是实战，都应该遵循一个结构化的流程。 + + + +::: tip 为什么要先澄清需求？ +很多人拿到题目就开始画图，结果设计了一个"正确但不是面试官想要的"系统。花 5 分钟问清楚需求，能避免后面 30 分钟的返工。 + +常见的澄清问题： +- 系统的核心功能是什么？（不要设计所有功能） +- 用户规模多大？（决定是否需要分布式） +- 读写比例？（决定缓存策略） +- 数据需要保留多久？（决定存储方案） +::: + +--- + +## 2. 容量估算：信封背面的艺术 + +"信封背面估算"（Back-of-envelope estimation）是系统设计中的核心技能。不需要精确计算，只需要知道量级。 + + + +### 常用换算速查 + +| 量级 | 换算 | 记忆技巧 | +|------|------|---------| +| 1 天 | 86,400 秒 | ≈ 10 万秒 | +| 1 亿请求/天 | ≈ 1,200 QPS | 除以 10 万 | +| 1 KB × 1 亿 | ≈ 100 GB | 1 亿条小记录 | +| 1 MB × 100 万 | ≈ 1 TB | 100 万张图片 | + +### 2-8 法则在估算中的应用 + +大多数系统遵循 80/20 法则：20% 的数据承载 80% 的请求。这意味着： + +- **缓存大小** ≈ 总数据量 × 20% +- **热点 QPS** ≈ 总 QPS × 80% 集中在 20% 的 key 上 +- **缓存命中率**目标 ≈ 80%+（低于这个值说明缓存策略有问题） + +--- + +## 3. 核心设计模式 + +系统设计中反复出现的模式，掌握这些就能应对大多数场景。 + +### 3.1 缓存模式 + +| 模式 | 读路径 | 写路径 | 适用场景 | +|------|--------|--------|---------| +| Cache-Aside | 先查缓存，miss 则查 DB 并回填 | 先写 DB，再删缓存 | 通用场景，最常用 | +| Read-Through | 缓存层自动从 DB 加载 | 同 Cache-Aside | 需要缓存框架支持 | +| Write-Behind | 同 Cache-Aside | 先写缓存，异步写 DB | 写密集型，可容忍丢数据 | + +::: tip 为什么是"删缓存"而不是"更新缓存"？ +更新缓存在并发场景下容易出现数据不一致：线程 A 和 B 同时更新，A 先写 DB 但 B 先更新缓存，导致缓存中是 B 的旧值。删除缓存则让下次读请求重新从 DB 加载，天然避免这个问题。 +::: + +### 3.2 分库分表 + +当单表数据量超过千万级，或单库 QPS 超过瓶颈时，就需要考虑分库分表。 + +| 策略 | 做法 | 优点 | 缺点 | +|------|------|------|------| +| 垂直分库 | 按业务域拆分数据库 | 业务解耦，独立扩展 | 跨库 JOIN 困难 | +| 水平分表 | 同一张表按规则拆成多张 | 单表数据量可控 | 分片键选择关键 | +| 垂直分表 | 把大字段拆到独立表 | 减少 IO，提升查询效率 | 需要额外 JOIN | + +**分片键选择原则**： +- 选择查询最频繁的字段（如 user_id） +- 数据分布要均匀，避免热点 +- 尽量让同一用户的数据在同一分片（减少跨分片查询） + +### 3.3 消息队列 + +消息队列是分布式系统的"减震器"，核心作用是解耦、异步、削峰。 + +| 场景 | 不用队列 | 用队列 | +|------|---------|--------| +| 下单后发通知 | 下单接口同步调用通知服务，通知失败导致下单失败 | 下单成功后发消息，通知服务异步消费 | +| 秒杀抢购 | 瞬间流量打爆数据库 | 请求先入队列，后端按能力消费 | +| 数据同步 | 服务 A 直接调用服务 B 的接口 | 服务 A 发事件，服务 B 订阅处理 | + +--- + +## 4. 权衡思维：没有银弹 + +架构设计的本质是权衡（Trade-off）。每个决策都有代价，关键是理解代价并做出适合当前阶段的选择。 + +| 权衡维度 | 选项 A | 选项 B | 决策依据 | +|---------|--------|--------|---------| +| 一致性 vs 可用性 | 强一致（CP） | 高可用（AP） | 业务能否容忍短暂不一致？ | +| 性能 vs 成本 | 全量缓存 | 按需缓存 | 数据量和预算 | +| 简单 vs 灵活 | 单体架构 | 微服务 | 团队规模和业务复杂度 | +| 实时 vs 批量 | 流式处理 | 批处理 | 数据时效性要求 | +| 自建 vs 托管 | 自己搭 MySQL | 用云数据库 RDS | 运维能力和成本 | + +::: tip 架构决策记录（ADR） +每个重要的架构决策都应该记录下来：**背景是什么、考虑了哪些方案、为什么选了这个、有什么代价**。这不是为了甩锅，而是为了让后来的人理解"为什么当时这么设计"。 + +格式很简单： +- **标题**：用 XXX 替代 YYY +- **背景**：我们遇到了什么问题 +- **决策**：我们选择了什么方案 +- **理由**：为什么选这个 +- **代价**：这个决策的缺点和风险 +::: + +### 常见的错误权衡 + +| 错误 | 表现 | 正确做法 | +|------|------|---------| +| 过早优化 | 日活 1000 就上分库分表 | 先用单库，遇到瓶颈再拆 | +| 技术驱动 | "我想用 Kafka" 而不是 "我需要异步" | 从问题出发，而非从技术出发 | +| 忽略运维成本 | 选了最优方案但团队维护不了 | 方案要匹配团队能力 | +| 追求完美一致性 | 所有场景都用分布式事务 | 大多数场景最终一致性就够了 | + +--- + +## 5. 经典案例 + +通过三个经典案例，把前面学到的方法论串起来。 + +### 5.1 短链服务（TinyURL） + +短链服务是系统设计面试的经典题目，麻雀虽小五脏俱全。 + +**需求澄清**： +- 核心功能：长链接 → 短链接（写），短链接 → 重定向（读） +- 读写比：约 100:1（读远多于写） +- 日均重定向：1 亿次 +- 短链永不过期 + +**容量估算**： + +| 指标 | 计算 | 结果 | +|------|------|------| +| 写 QPS | 1 亿 / 100 / 86400 | ≈ 12 QPS | +| 读 QPS | 1 亿 / 86400 | ≈ 1,200 QPS | +| 峰值读 QPS | 1,200 × 3 | ≈ 3,600 QPS | +| 5 年存储 | 100 万/天 × 365 × 5 × 100B | ≈ 18 GB | +| 缓存（20%） | 18 GB × 20% | ≈ 3.6 GB | + +**架构设计**： + +``` +写路径：客户端 → API Server → ID 生成器 → Base62 编码 → 写入 MySQL + Redis +读路径：客户端 → CDN → API Server → Redis 查询 → 302 重定向 + ↓ (cache miss) + MySQL 查询 → 回填 Redis +``` + +**关键设计决策**： +- 短码生成：Snowflake 分布式 ID + Base62 编码，避免哈希冲突 +- 缓存策略：Cache-Aside，热点短链用 CDN 加速 +- 数据库：单表即可（18GB 很小），按短码做索引 + +### 5.2 Feed 流系统 + +社交平台的 Feed 流（朋友圈、微博首页）是另一个经典题目。 + +**核心挑战**：用户发一条动态，如何让所有关注者看到？ + +| 方案 | 做法 | 优点 | 缺点 | +|------|------|------|------| +| 拉模式（Pull） | 读取时实时聚合关注者的动态 | 写入简单，存储少 | 读取慢，关注多时延迟高 | +| 推模式（Push） | 发布时写入所有粉丝的收件箱 | 读取极快 | 大 V 发动态写扩散严重 | +| 推拉结合 | 普通用户推，大 V 拉 | 平衡读写性能 | 实现复杂 | + +**推拉结合方案**： +- 粉丝数 < 1 万：发布时推送到所有粉丝的 Feed 缓存（推模式） +- 粉丝数 > 1 万：不推送，粉丝读取时实时拉取（拉模式） +- 用户打开 Feed 时：合并推送的内容 + 实时拉取大 V 的内容，按时间排序 + +### 5.3 秒杀系统 + +秒杀的核心挑战：瞬间超高并发 + 库存不能超卖。 + +**流量特征**： +- 活动开始前：大量用户刷新页面等待 +- 活动开始瞬间：QPS 可能是平时的 100 倍以上 +- 活动结束后：流量迅速回落 + +**分层削峰策略**： + +``` +用户请求 → CDN（静态页面）→ 网关（限流）→ 消息队列（削峰）→ 库存服务（扣减） +``` + +| 层级 | 策略 | 效果 | +|------|------|------| +| 前端 | 按钮置灰 + 随机延迟 + 验证码 | 过滤机器人，分散请求 | +| CDN | 静态资源缓存 | 减少 90% 的页面请求 | +| 网关 | 令牌桶限流 | 只放行系统能承受的流量 | +| 消息队列 | 请求入队，异步处理 | 削峰填谷，保护数据库 | +| 库存服务 | Redis 预扣减 + Lua 原子操作 | 防止超卖，毫秒级响应 | + +::: tip 秒杀的核心原则 +1. **尽量拦截在上游**：能在 CDN 挡住的就不要到应用层 +2. **读写分离**：商品详情页走缓存，只有下单走数据库 +3. **异步处理**：用户点击"抢购"后立即返回"排队中"，后台异步处理 +4. **兜底方案**：限流、熔断、降级，任何一层出问题都有 Plan B +::: + +--- + +## 总结 + +系统设计是一门实践性很强的技能，核心在于结构化思考和权衡取舍。 + +回顾本章的关键要点： + +1. **四步法框架**：需求澄清 → 容量估算 → 架构设计 → 深入优化，每一步都不可跳过 +2. **信封背面估算**：不需要精确，只需要知道量级，用于指导架构决策 +3. **核心模式**：缓存、分库分表、消息队列、CDN、限流熔断——这些是系统设计的"积木" +4. **权衡思维**：没有完美方案，只有适合当前阶段的方案，记录每个决策的理由和代价 +5. **经典案例**：短链服务练基础、Feed 流练推拉模型、秒杀练高并发——掌握这三个就能举一反三 + +## 延伸阅读 + +- [System Design Interview](https://www.amazon.com/System-Design-Interview-insiders-Second/dp/B08CMF2CQF) - Alex Xu 系统设计面试经典 +- [Designing Data-Intensive Applications](https://dataintensive.net/) - Martin Kleppmann 数据密集型应用设计 +- [The System Design Primer](https://github.com/donnemartin/system-design-primer) - GitHub 上最全的系统设计学习资源 +- [ByteByteGo](https://bytebytego.com/) - Alex Xu 的系统设计可视化博客 + diff --git a/docs/zh-cn/appendix/7-infrastructure-and-operations/docker-containers.md b/docs/zh-cn/appendix/7-infrastructure-and-operations/docker-containers.md index bb21e14..97f55fd 100644 --- a/docs/zh-cn/appendix/7-infrastructure-and-operations/docker-containers.md +++ b/docs/zh-cn/appendix/7-infrastructure-and-operations/docker-containers.md @@ -1,3 +1,221 @@ # Docker 容器化 -> 待实现 +::: tip 前言 +**"在我机器上能跑"是开发者最经典的借口，Docker 让这个借口彻底消失。** 容器化技术将应用及其所有依赖打包成一个标准化的单元，确保在任何环境中都能一致运行。它是现代软件交付的基石。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **核心概念**：理解镜像、容器、仓库三大核心概念 +- **架构对比**：明白容器和虚拟机的本质区别 +- **实操能力**：掌握 Dockerfile 编写和常用命令 +- **编排基础**：学会用 Docker Compose 管理多服务应用 +- **最佳实践**：了解镜像优化、安全加固等生产级实践 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 为什么需要容器 | 环境一致性、资源效率、标准化交付 | +| **第 2 章** | 核心概念 | 镜像、容器、仓库、Dockerfile | +| **第 3 章** | Docker 生命周期 | 编写、构建、推送、运行、管理 | +| **第 4 章** | Docker Compose | 多服务编排、网络、数据卷 | +| **第 5 章** | 最佳实践 | 镜像优化、安全、多阶段构建 | + +--- + +## 1. 为什么需要容器？ + +在容器出现之前，部署一个应用需要在服务器上手动安装运行时、配置环境变量、处理依赖冲突。不同环境（开发、测试、生产）之间的差异是 bug 的温床。 + + + +### 容器解决了什么问题？ + +| 问题 | 传统方式 | 容器方式 | +|------|---------|---------| +| 环境不一致 | "我本地能跑" | 打包所有依赖，到处一致 | +| 依赖冲突 | App A 要 Node 14，App B 要 Node 18 | 每个容器独立环境 | +| 资源浪费 | 每个 VM 一个完整 OS | 共享内核，MB 级开销 | +| 部署慢 | 手动安装配置 | docker run 一条命令 | +| 扩容难 | 新建 VM、装环境、部署 | 秒级启动新容器 | + +::: tip 容器的本质 +容器不是轻量级虚拟机。它的本质是**被隔离的进程**。Linux 内核通过两个机制实现容器： +- **Namespace**：隔离进程的视野（PID、网络、文件系统等） +- **Cgroups**：限制进程的资源使用（CPU、内存、IO） + +容器里的进程和宿主机上的普通进程没有本质区别，只是被"关在了一个看不到外面的房间里"。 +::: + +--- + +## 2. 核心概念 + +Docker 的世界围绕三个核心概念：镜像（Image）、容器（Container）、仓库（Registry）。 + +| 概念 | 类比 | 说明 | +|------|------|------| +| 镜像（Image） | 类 / 模板 | 只读的应用模板，包含代码、运行时、库、配置 | +| 容器（Container） | 实例 / 对象 | 镜像的运行实例，可读写，有独立的生命周期 | +| 仓库（Registry） | 应用商店 | 存储和分发镜像的服务（Docker Hub、ACR、ECR） | +| Dockerfile | 配方 / 蓝图 | 定义如何构建镜像的文本文件 | +| 数据卷（Volume） | 外接硬盘 | 持久化数据，容器删除后数据不丢失 | + +### 镜像的分层结构 + +Docker 镜像由多个只读层（Layer）叠加而成，每条 Dockerfile 指令创建一层： + +``` +┌─────────────────────────┐ +│ CMD ["node", "app.js"] │ ← 启动命令层 +├─────────────────────────┤ +│ COPY . /app │ ← 应用代码层（经常变） +├─────────────────────────┤ +│ RUN npm install │ ← 依赖安装层（偶尔变） +├─────────────────────────┤ +│ FROM node:18-alpine │ ← 基础镜像层（很少变） +└─────────────────────────┘ +``` + +::: tip 为什么分层很重要？ +Docker 会缓存每一层。如果某一层没有变化，构建时会直接复用缓存。所以 Dockerfile 中应该把**变化频率低的指令放在前面**（如安装依赖），**变化频率高的放在后面**（如复制代码）。这样大部分构建都能命中缓存，速度快很多。 +::: + +--- + +## 3. Docker 生命周期 + +从编写 Dockerfile 到容器运行，Docker 的工作流程是一条清晰的流水线。 + + + +### Dockerfile 常用指令速查 + +| 指令 | 作用 | 示例 | +|------|------|------| +| `FROM` | 指定基础镜像 | `FROM node:18-alpine` | +| `WORKDIR` | 设置工作目录 | `WORKDIR /app` | +| `COPY` | 复制文件到镜像 | `COPY package.json ./` | +| `RUN` | 构建时执行命令 | `RUN npm install` | +| `ENV` | 设置环境变量 | `ENV NODE_ENV=production` | +| `EXPOSE` | 声明端口（仅文档作用） | `EXPOSE 3000` | +| `CMD` | 容器启动命令 | `CMD ["node", "app.js"]` | +| `ENTRYPOINT` | 容器入口点（不易被覆盖） | `ENTRYPOINT ["nginx"]` | + +--- + +## 4. Docker Compose：多服务编排 + +真实项目通常不止一个容器。一个 Web 应用可能需要：应用服务器 + 数据库 + Redis + Nginx。Docker Compose 用一个 YAML 文件定义和管理多个容器。 + +### docker-compose.yml 示例 + +```yaml +version: '3.8' +services: + app: + build: . + ports: + - "3000:3000" + environment: + - DB_HOST=db + - REDIS_HOST=redis + depends_on: + - db + - redis + + db: + image: postgres:15-alpine + volumes: + - db-data:/var/lib/postgresql/data + environment: + - POSTGRES_PASSWORD=secret + + redis: + image: redis:7-alpine + +volumes: + db-data: +``` + +### Compose 核心概念 + +| 概念 | 说明 | 示例 | +|------|------|------| +| services | 定义各个容器服务 | app、db、redis | +| volumes | 持久化数据卷 | db-data 保存数据库文件 | +| networks | 自定义网络（默认自动创建） | 服务间通过服务名互相访问 | +| depends_on | 启动顺序依赖 | app 依赖 db 和 redis | +| environment | 环境变量 | 数据库密码、连接地址 | + +::: tip 服务发现 +在 Docker Compose 中，服务名就是主机名。app 容器可以直接用 `db:5432` 访问数据库，用 `redis:6379` 访问 Redis，不需要知道 IP 地址。这是 Docker 内置 DNS 的功劳。 +::: + +--- + +## 5. 最佳实践 + +### 5.1 多阶段构建（Multi-stage Build） + +多阶段构建是优化镜像大小的利器。构建阶段安装所有工具和依赖，最终阶段只保留运行时需要的文件。 + +```dockerfile +# 构建阶段 +FROM node:18-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +RUN npm run build + +# 运行阶段 +FROM node:18-alpine +WORKDIR /app +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/node_modules ./node_modules +EXPOSE 3000 +CMD ["node", "dist/server.js"] +``` + +### 5.2 镜像优化清单 + +| 优化项 | 做法 | 效果 | +|--------|------|------| +| 选择小基础镜像 | 用 `alpine` 而非 `ubuntu` | 镜像从 ~200MB 降到 ~50MB | +| 合并 RUN 指令 | 多个命令用 `&&` 连接 | 减少镜像层数 | +| 使用 .dockerignore | 排除 node_modules、.git 等 | 加速构建，减小上下文 | +| 多阶段构建 | 分离构建和运行环境 | 最终镜像不含构建工具 | +| 固定版本号 | `node:18.17-alpine` 而非 `node:latest` | 构建可重复 | + +### 5.3 安全实践 + +| 实践 | 说明 | +|------|------| +| 不用 root 运行 | `USER node` 指定非 root 用户 | +| 扫描漏洞 | `docker scout` 或 Trivy 扫描镜像 | +| 最小权限 | 只安装必要的包，不装调试工具 | +| 不硬编码密钥 | 用环境变量或 Docker Secrets | +| 定期更新基础镜像 | 及时修复安全漏洞 | + +--- + +## 总结 + +Docker 容器化是现代软件交付的基础设施，理解它对于任何开发者都至关重要。 + +回顾本章的关键要点： + +1. **容器 vs 虚拟机**：容器共享宿主内核，更轻量、更快，但隔离性略弱于 VM +2. **核心三件套**：镜像（模板）、容器（实例）、仓库（分发） +3. **Dockerfile**：分层构建，利用缓存，变化少的指令放前面 +4. **Docker Compose**：用 YAML 定义多服务应用，服务名即主机名 +5. **生产实践**：多阶段构建减小镜像、alpine 基础镜像、非 root 运行 + +## 延伸阅读 + +- [Docker 官方文档](https://docs.docker.com/) - 最权威的参考资料 +- [Docker Getting Started](https://docs.docker.com/get-started/) - 官方入门教程 +- [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) - 官方最佳实践指南 +- [Docker Compose 文档](https://docs.docker.com/compose/) - Compose 完整参考 diff --git a/docs/zh-cn/appendix/7-infrastructure-and-operations/kubernetes.md b/docs/zh-cn/appendix/7-infrastructure-and-operations/kubernetes.md index 66b08cf..290add1 100644 --- a/docs/zh-cn/appendix/7-infrastructure-and-operations/kubernetes.md +++ b/docs/zh-cn/appendix/7-infrastructure-and-operations/kubernetes.md @@ -1,3 +1,192 @@ # Kubernetes 编排 -> 待实现 +::: tip 前言 +**Docker 解决了"打包"问题，Kubernetes 解决了"管理"问题。** 当你有几十上百个容器需要部署、扩缩容、故障恢复时，手动管理是不现实的。Kubernetes（K8s）就是容器的"操作系统"，它自动化了容器化应用的部署、扩展和运维。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **架构理解**：掌握 K8s 控制平面和工作节点的组成 +- **核心资源**：熟悉 Pod、Deployment、Service 等核心概念 +- **声明式管理**：理解"声明期望状态，系统自动收敛"的思想 +- **运维能力**：了解滚动更新、自动扩缩容、健康检查等机制 +- **实战入门**：能用 kubectl 和 YAML 部署一个完整应用 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 为什么需要 K8s | 容器编排的挑战 | +| **第 2 章** | K8s 架构 | 控制平面、工作节点、etcd | +| **第 3 章** | 核心资源 | Pod、Deployment、Service、Ingress | +| **第 4 章** | 声明式管理 | YAML、kubectl、控制循环 | +| **第 5 章** | 运维实践 | 滚动更新、HPA、健康检查 | + +--- + +## 1. 为什么需要 Kubernetes？ + +Docker 让单个容器的打包和运行变得简单，但当你面对以下场景时，手动管理就力不从心了： + +| 挑战 | 描述 | K8s 的解决方案 | +|------|------|---------------| +| 多实例部署 | 一个服务需要运行 10 个副本 | Deployment 自动管理副本数 | +| 故障恢复 | 某个容器挂了需要自动重启 | 控制器自动检测并重建 Pod | +| 服务发现 | 容器 IP 会变，怎么找到对方？ | Service 提供稳定的 DNS 和 IP | +| 滚动更新 | 更新版本时不能停服 | 逐步替换旧 Pod，零停机 | +| 弹性伸缩 | 流量高峰自动扩容 | HPA 根据 CPU/内存自动调整副本数 | +| 资源调度 | 把容器放到最合适的机器上 | Scheduler 智能调度 | + +::: tip K8s 的核心思想：声明式 +你不需要告诉 K8s "启动 3 个容器"（命令式），而是告诉它 "我要 3 个副本在运行"（声明式）。K8s 会持续监控，确保实际状态与你声明的期望状态一致。如果一个 Pod 挂了，它会自动创建新的来补上。 +::: + +--- + +## 2. Kubernetes 架构 + +K8s 集群由控制平面（Control Plane）和工作节点（Worker Node）组成。 + + + +### 一次请求的完整路径 + +``` +用户请求 → Ingress Controller → Service → kube-proxy → Pod（容器） + ↑ + Endpoint 列表（由 Service 维护） +``` + +--- + +## 3. 核心资源对象 + +K8s 通过各种"资源对象"来描述集群的期望状态。 + + + +### 资源对象分类 + +| 类别 | 资源 | 用途 | +|------|------|------| +| 工作负载 | Pod、Deployment、StatefulSet、DaemonSet、Job | 运行应用 | +| 网络 | Service、Ingress、NetworkPolicy | 服务发现和流量管理 | +| 配置 | ConfigMap、Secret | 配置和敏感数据管理 | +| 存储 | PersistentVolume、PersistentVolumeClaim | 持久化存储 | +| 调度 | Node、Namespace、ResourceQuota | 资源隔离和限制 | + +--- + +## 4. 声明式管理与 kubectl + +### 控制循环（Reconciliation Loop） + +K8s 的核心工作机制是控制循环： + +``` +观察（Observe）→ 比较（Diff）→ 行动（Act）→ 观察... + ↓ ↓ ↓ + 读取实际状态 与期望状态对比 执行修正操作 +``` + +你声明 `replicas: 3`，控制器发现只有 2 个 Pod 在运行，就会创建 1 个新的。这个循环每隔几秒执行一次，确保系统始终向期望状态收敛。 + +### kubectl 常用命令 + +| 命令 | 作用 | 示例 | +|------|------|------| +| `kubectl apply -f` | 应用 YAML 配置 | `kubectl apply -f deployment.yaml` | +| `kubectl get` | 查看资源列表 | `kubectl get pods -o wide` | +| `kubectl describe` | 查看资源详情 | `kubectl describe pod my-app-xxx` | +| `kubectl logs` | 查看 Pod 日志 | `kubectl logs -f my-app-xxx` | +| `kubectl exec` | 进入 Pod 终端 | `kubectl exec -it my-app-xxx -- sh` | +| `kubectl delete` | 删除资源 | `kubectl delete -f deployment.yaml` | +| `kubectl scale` | 手动扩缩容 | `kubectl scale deploy my-app --replicas=5` | + +::: tip apply vs create +`kubectl create` 是命令式的——"创建这个资源"，如果已存在会报错。`kubectl apply` 是声明式的——"确保资源是这个状态"，不存在就创建，已存在就更新。生产环境中应该始终使用 `apply`。 +::: + +--- + +## 5. 运维实践 + +### 5.1 滚动更新与回滚 + +Deployment 默认使用滚动更新策略：逐步创建新版本 Pod，同时逐步终止旧版本 Pod。 + +```yaml +spec: + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 # 最多多创建 1 个 Pod + maxUnavailable: 0 # 不允许有 Pod 不可用 +``` + +| 操作 | 命令 | +|------|------| +| 更新镜像 | `kubectl set image deploy/my-app app=my-app:2.0` | +| 查看更新状态 | `kubectl rollout status deploy/my-app` | +| 查看历史版本 | `kubectl rollout history deploy/my-app` | +| 回滚到上一版本 | `kubectl rollout undo deploy/my-app` | + +### 5.2 自动扩缩容（HPA） + +HPA（Horizontal Pod Autoscaler）根据 CPU、内存或自定义指标自动调整 Pod 副本数。 + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: my-app-hpa +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: my-app + minReplicas: 2 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 +``` + +### 5.3 健康检查（Probe） + +K8s 通过三种探针监控 Pod 的健康状态： + +| 探针 | 作用 | 失败后果 | +|------|------|---------| +| livenessProbe | 检测容器是否存活 | 重启容器 | +| readinessProbe | 检测容器是否就绪 | 从 Service 摘除，不接收流量 | +| startupProbe | 检测容器是否启动完成 | 启动期间不执行其他探针 | + +::: tip 探针的重要性 +没有配置健康检查的 Pod，K8s 只能通过进程是否存在来判断健康状态。但很多时候进程还在，服务已经不响应了（比如死锁、OOM 边缘）。配置 livenessProbe 可以让 K8s 自动重启这些"假死"的容器。 +::: + +--- + +## 总结 + +Kubernetes 是容器编排的事实标准，理解它的核心概念是云原生开发的基础。 + +回顾本章的关键要点： + +1. **声明式管理**：告诉 K8s "我要什么"，而不是"怎么做"，控制循环自动收敛 +2. **架构分层**：控制平面负责决策，工作节点负责执行，etcd 存储状态 +3. **核心资源**：Pod（最小单元）、Deployment（副本管理）、Service（服务发现）、Ingress（外部入口） +4. **运维自动化**：滚动更新零停机、HPA 弹性伸缩、探针自动故障恢复 +5. **配置分离**：ConfigMap 和 Secret 让配置与镜像解耦 + +## 延伸阅读 + +- [Kubernetes 官方文档](https://kubernetes.io/zh-cn/docs/) - 最权威的中文参考 +- [Kubernetes the Hard Way](https://github.com/kelseyhightower/kubernetes-the-hard-way) - 从零手动搭建 K8s 集群 +- [The Illustrated Children's Guide to Kubernetes](https://www.cncf.io/phippy/) - CNCF 出品的趣味入门 +- [Kubernetes Patterns](https://www.oreilly.com/library/view/kubernetes-patterns-2nd/9781098131678/) - K8s 设计模式 diff --git a/docs/zh-cn/appendix/7-infrastructure-and-operations/linux-basics.md b/docs/zh-cn/appendix/7-infrastructure-and-operations/linux-basics.md index 0f2d948..0632287 100644 --- a/docs/zh-cn/appendix/7-infrastructure-and-operations/linux-basics.md +++ b/docs/zh-cn/appendix/7-infrastructure-and-operations/linux-basics.md @@ -1,3 +1,397 @@ # Linux 基础 -> 待实现 +::: tip 前言 +**服务器的世界，Linux 是绝对的主角。** 全球超过 90% 的服务器运行 Linux，从你每天用的微信到 Google 搜索，背后都是 Linux 在支撑。作为开发者，掌握 Linux 基础不是可选项，而是必修课。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **文件系统**：理解 Linux 目录结构和"一切皆文件"的哲学 +- **常用命令**：掌握文件操作、文本处理、进程管理等核心命令 +- **权限模型**：理解用户、组、权限的概念 +- **Shell 基础**：了解管道、重定向、环境变量等 Shell 核心概念 +- **实战技能**：学会日志查看、进程排查、网络诊断等运维基本功 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 文件系统 | 目录结构、一切皆文件 | +| **第 2 章** | 常用命令 | 文件、文本、进程、网络 | +| **第 3 章** | 权限模型 | 用户、组、rwx、sudo | +| **第 4 章** | Shell 基础 | 管道、重定向、变量、脚本 | +| **第 5 章** | 实战场景 | 日志排查、性能诊断 | + +--- + +## 1. 文件系统：一切皆文件 + +Linux 最核心的哲学之一就是**一切皆文件**。普通文件是文件，目录是文件，硬盘是文件，甚至网络连接、进程信息都是文件。这个统一的抽象让你可以用同一套工具（读、写、权限控制）操作几乎所有系统资源。 + + + +### 目录结构速记 + +把 Linux 文件系统想象成一棵倒过来的树： + +``` +/ ← 根目录（树根） +├── home/ ← 用户的家（你的文件都在这） +├── etc/ ← 配置文件（系统的"设置面板"） +├── var/ ← 变化的数据（日志、缓存） +├── usr/ ← 用户安装的程序 +├── tmp/ ← 临时文件（重启就没了） +├── proc/ ← 进程信息（虚拟的，不占磁盘） +├── dev/ ← 设备文件（硬盘、终端） +├── bin/ ← 基础命令（ls、cp、mv） +├── sbin/ ← 系统管理命令（需要 root） +├── opt/ ← 第三方软件 +└── root/ ← root 用户的家目录 +``` + +### 路径的两种写法 + +| 类型 | 格式 | 示例 | 说明 | +|------|------|------|------| +| 绝对路径 | 从 `/` 开始 | `/home/alice/code/app.js` | 从根目录出发，不会歧义 | +| 相对路径 | 从当前目录开始 | `./code/app.js` 或 `../config` | `.` 是当前目录，`..` 是上级目录 | + +::: tip "一切皆文件"的威力 +想知道 CPU 信息？读文件：`cat /proc/cpuinfo` +想知道内存使用？读文件：`cat /proc/meminfo` +想产生随机数？读文件：`cat /dev/urandom` +想丢弃输出？写文件：`echo "no thanks" > /dev/null` + +不需要专门的 API，读写文件就够了。这就是 Unix 哲学的优雅之处。 +::: + +--- + +## 2. 常用命令 + +Linux 命令遵循一个统一的格式：`命令 [选项] [参数]`。比如 `ls -la /home` 中，`ls` 是命令，`-la` 是选项，`/home` 是参数。 + + + +### 最常用的 10 个命令 + +如果只能记住 10 个命令，记这些： + +| 命令 | 用途 | 记忆技巧 | +|------|------|----------| +| `ls` | 列出文件 | list | +| `cd` | 切换目录 | change directory | +| `cat` | 查看文件 | concatenate | +| `grep` | 搜索文本 | global regular expression print | +| `find` | 查找文件 | 就是 find | +| `ps` | 查看进程 | process status | +| `tail -f` | 实时看日志 | 看文件"尾巴"，-f 是 follow | +| `chmod` | 改权限 | change mode | +| `curl` | 发 HTTP 请求 | client URL | +| `ssh` | 远程登录 | secure shell | + +### 命令组合的艺术 + +Linux 的强大不在于单个命令，而在于**命令组合**。通过管道 `|` 把多个简单命令串起来，解决复杂问题： + +```bash +# 找出占用 CPU 最多的 5 个进程 +ps aux --sort=-%cpu | head -6 + +# 统计日志中出现最多的错误类型 +grep "ERROR" app.log | awk '{print $4}' | sort | uniq -c | sort -rn | head -10 + +# 查找大于 100MB 的文件 +find / -size +100M -type f 2>/dev/null + +# 实时监控日志中的错误 +tail -f /var/log/app.log | grep --color "ERROR" +``` + +::: tip Unix 哲学 +"做一件事，做好它。" 每个命令只负责一个功能，通过管道组合实现复杂操作。这就是为什么 Linux 命令都很短小——它们是积木，不是瑞士军刀。 +::: + +--- + +## 3. 权限模型 + +Linux 是多用户系统，权限模型是安全的基石。每个文件都有三组权限，分别控制**所有者（Owner）**、**所属组（Group）**、**其他人（Others）**能做什么。 + +### 读懂 `ls -l` 的输出 + +```bash +$ ls -l app.js +-rwxr-xr-- 1 alice developers 2048 Jan 15 10:30 app.js +│├──┤├──┤├──┤ │ │ │ +│ │ │ │ │ │ └── 文件大小 +│ │ │ │ │ └── 所属组 +│ │ │ │ └── 所有者 +│ │ │ └── 其他人权限：r-- (只读) +│ │ └── 组权限：r-x (读+执行) +│ └── 所有者权限：rwx (读+写+执行) +└── 文件类型：- 普通文件，d 目录，l 链接 +``` + +### 权限的三种操作 + +| 权限 | 字母 | 数字 | 对文件的含义 | 对目录的含义 | +|------|------|------|-------------|-------------| +| 读 | `r` | 4 | 查看文件内容 | 列出目录内容（ls） | +| 写 | `w` | 2 | 修改文件内容 | 创建/删除目录中的文件 | +| 执行 | `x` | 1 | 运行程序/脚本 | 进入目录（cd） | + + + +### 数字权限速算 + +三个数字分别代表 Owner、Group、Others 的权限，每个数字是 r(4) + w(2) + x(1) 的和： + +``` +chmod 755 script.sh + 7 = rwx (4+2+1) → 所有者：读+写+执行 + 5 = r-x (4+0+1) → 组：读+执行 + 5 = r-x (4+0+1) → 其他人：读+执行 +``` + +| 常见权限 | 含义 | 典型用途 | +|---------|------|---------| +| `644` | rw-r--r-- | 普通文件（所有者可写，其他人只读） | +| `755` | rwxr-xr-x | 可执行文件/目录 | +| `600` | rw------- | 私密文件（如 SSH 密钥） | +| `777` | rwxrwxrwx | 所有人可读写执行（危险，避免使用） | + +### sudo：临时获取超级权限 + +普通用户权限有限，有些操作需要 root 权限。`sudo` 让你临时以 root 身份执行命令： + +```bash +# 普通用户无法修改系统配置 +$ vim /etc/nginx/nginx.conf +# Permission denied + +# 用 sudo 临时提权 +$ sudo vim /etc/nginx/nginx.conf +# 输入你的密码后可以编辑 + +# 切换到 root 用户（谨慎使用） +$ sudo su - +``` + +::: warning 最小权限原则 +永远不要用 `chmod 777` 解决权限问题，这等于把门锁拆了。正确做法是搞清楚谁需要什么权限，精确授予。同样，不要长期以 root 身份操作，只在必要时用 `sudo`。 +::: + +--- + +## 4. Shell 基础 + +Shell 是你和 Linux 内核之间的"翻译官"。你输入命令，Shell 解释并交给内核执行。最常用的 Shell 是 **Bash**（大多数 Linux 发行版默认）和 **Zsh**（macOS 默认）。 + +### 管道与重定向 + +这是 Shell 最强大的两个特性： + +| 符号 | 名称 | 作用 | 示例 | +|------|------|------|------| +| `|` | 管道 | 把前一个命令的输出作为后一个的输入 | `cat log | grep ERROR` | +| `>` | 输出重定向 | 把输出写入文件（覆盖） | `echo "hello" > file.txt` | +| `>>` | 追加重定向 | 把输出追加到文件末尾 | `echo "world" >> file.txt` | +| `<` | 输入重定向 | 从文件读取输入 | `wc -l < file.txt` | +| `2>` | 错误重定向 | 把错误信息写入文件 | `cmd 2> error.log` | +| `2>&1` | 合并输出 | 把错误和正常输出合并 | `cmd > all.log 2>&1` | + +### 环境变量 + +环境变量是 Shell 中的"全局配置"，影响命令的行为： + +```bash +# 查看所有环境变量 +env + +# 查看某个变量 +echo $PATH +echo $HOME + +# 临时设置（只在当前 Shell 有效） +export API_KEY="abc123" + +# 永久设置（写入配置文件） +echo 'export API_KEY="abc123"' >> ~/.bashrc +source ~/.bashrc # 让配置立即生效 +``` + +| 常见变量 | 含义 | 示例值 | +|---------|------|--------| +| `$PATH` | 命令搜索路径 | `/usr/local/bin:/usr/bin:/bin` | +| `$HOME` | 用户主目录 | `/home/alice` | +| `$USER` | 当前用户名 | `alice` | +| `$PWD` | 当前工作目录 | `/var/log` | +| `$SHELL` | 当前使用的 Shell | `/bin/bash` | + +### Shell 脚本入门 + +把多个命令写进一个文件，就是 Shell 脚本。它是自动化运维的起点： + +```bash +#!/bin/bash +# deploy.sh - 简单的部署脚本 + +APP_DIR="/opt/myapp" +LOG_FILE="/var/log/deploy.log" + +echo "$(date) - 开始部署..." >> $LOG_FILE + +# 拉取最新代码 +cd $APP_DIR && git pull origin main + +# 安装依赖 +npm install --production + +# 重启服务 +pm2 restart myapp + +echo "$(date) - 部署完成" >> $LOG_FILE +``` + +```bash +# 给脚本执行权限并运行 +chmod +x deploy.sh +./deploy.sh +``` + +::: tip 脚本调试技巧 +在脚本开头加 `set -ex`：`-e` 让脚本遇到错误立即退出（而不是继续执行），`-x` 会打印每条执行的命令（方便排查问题）。这两个选项在生产脚本中几乎是标配。 +::: + +--- + +## 5. 实战场景 + +理论学完了，来看几个开发中最常遇到的实战场景。 + +### 5.1 日志排查 + +服务出问题，第一反应就是看日志。以下是日志排查的常用套路： + +```bash +# 1. 实时跟踪日志（最常用） +tail -f /var/log/app/error.log + +# 2. 搜索特定时间段的错误 +grep "2024-01-15 14:" error.log | grep "ERROR" + +# 3. 统计每小时的错误数量 +grep "ERROR" app.log | awk '{print substr($1,1,13)}' | uniq -c + +# 4. 查看最近 100 行日志 +tail -100 app.log + +# 5. 在多个日志文件中搜索 +grep -r "OutOfMemory" /var/log/app/ +``` + +### 5.2 进程排查 + +应用卡死、CPU 飙高、内存泄漏——这些问题都需要从进程入手： + +```bash +# 查看 CPU 占用最高的进程 +ps aux --sort=-%cpu | head -10 + +# 查看内存占用最高的进程 +ps aux --sort=-%mem | head -10 + +# 查找特定进程 +ps aux | grep "node" + +# 查看进程的详细信息（包括线程） +top -Hp + +# 查看进程打开的文件 +lsof -p + +# 优雅终止进程（SIGTERM） +kill + +# 强制终止（SIGKILL，最后手段） +kill -9 +``` + +### 5.3 网络诊断 + +服务连不上？先搞清楚是网络问题还是应用问题： + +```bash +# 测试目标是否可达 +ping -c 4 google.com + +# 检查端口是否开放 +telnet db-server 3306 +# 或者用 nc +nc -zv db-server 3306 + +# 查看本机监听的端口 +ss -tlnp +# 或 +netstat -tlnp + +# DNS 解析检查 +dig api.example.com +nslookup api.example.com + +# 测试 HTTP 接口 +curl -v http://localhost:3000/health + +# 查看网络连接状态统计 +ss -s +``` + +### 5.4 磁盘空间排查 + +磁盘满了是线上最常见的故障之一： + +```bash +# 查看各分区使用情况 +df -h + +# 找出占用空间最大的目录 +du -sh /* 2>/dev/null | sort -rh | head -10 + +# 进一步定位大目录 +du -sh /var/log/* | sort -rh | head -10 + +# 查找大文件（>100MB） +find / -type f -size +100M 2>/dev/null | head -20 + +# 清理常见的空间占用 +# 清理旧日志 +sudo journalctl --vacuum-size=500M +# 清理 Docker 无用镜像 +docker system prune -a +``` + +::: tip 线上排查口诀 +**"一看日志，二看进程，三看网络，四看磁盘"**。90% 的线上问题都能通过这四步定位到原因。养成习惯后，排查效率会大幅提升。 +::: + +--- + +## 总结 + +Linux 是开发者的必备技能，掌握基础就能应对大部分日常开发和运维场景。 + +回顾本章的关键要点： + +1. **一切皆文件**：Linux 用文件抽象统一了对硬件、进程、网络等资源的访问方式 +2. **命令组合**：单个命令功能简单，通过管道 `|` 组合才能发挥真正威力 +3. **权限模型**：Owner/Group/Others × Read/Write/Execute，用数字（如 755）快速设置 +4. **Shell 基础**：管道、重定向、环境变量、脚本是自动化的基石 +5. **实战排查**：日志 → 进程 → 网络 → 磁盘，四步定位大部分线上问题 + +## 延伸阅读 + +- [Linux 命令大全](https://man7.org/linux/man-pages/) - Linux man pages 官方文档 +- [The Linux Command Line](https://linuxcommand.org/tlcl.php) - 免费的 Linux 命令行入门书 +- [Linux Journey](https://linuxjourney.com/) - 交互式 Linux 学习网站 +- [explainshell.com](https://explainshell.com/) - 输入命令自动解释每个参数的含义 diff --git a/docs/zh-cn/appendix/8-artificial-intelligence/neural-networks.md b/docs/zh-cn/appendix/8-artificial-intelligence/neural-networks.md index ca99535..8bad2d2 100644 --- a/docs/zh-cn/appendix/8-artificial-intelligence/neural-networks.md +++ b/docs/zh-cn/appendix/8-artificial-intelligence/neural-networks.md @@ -1,3 +1,315 @@ # 神经网络与深度学习 -> 待实现 +::: tip 前言 +**神经网络是 AI 革命的引擎。** 从 ChatGPT 的语言理解到自动驾驶的图像识别，背后都是神经网络在工作。它不是魔法，而是一套精巧的数学框架——通过大量数据"学习"出输入到输出的映射关系。理解它的基本原理，能帮你更好地使用和调试 AI 工具。 +::: + +**这篇文章会带你学什么？** + +学完这章后，你将获得： + +- **核心概念**：理解神经元、层、前向传播、反向传播的基本原理 +- **网络类型**：了解 CNN、RNN、Transformer 等主流架构的特点和适用场景 +- **训练过程**：明白模型是如何从数据中"学习"的 +- **关键技巧**：掌握过拟合、学习率、正则化等实用概念 +- **发展脉络**：了解从感知机到大语言模型的演进历程 + +| 章节 | 内容 | 核心概念 | +|-----|------|---------| +| **第 1 章** | 从神经元到网络 | 感知机、激活函数、前向传播 | +| **第 2 章** | 网络如何学习 | 损失函数、梯度下降、反向传播 | +| **第 3 章** | 主流网络架构 | CNN、RNN、Transformer | +| **第 4 章** | 训练的艺术 | 过拟合、正则化、超参数调优 | +| **第 5 章** | 发展历程与前沿 | 从感知机到 GPT | + +--- + +## 1. 从神经元到网络 + +### 单个神经元 + +神经网络的最小单元是**神经元**（Neuron）。它模拟了生物神经元的工作方式：接收多个输入信号，加权求和，通过激活函数产生输出。 + +``` +输入 x1 ──→ ×w1 ──┐ +输入 x2 ──→ ×w2 ──┼──→ Σ(加权求和) + b(偏置) ──→ f(激活函数) ──→ 输出 +输入 x3 ──→ ×w3 ──┘ +``` + +数学表达：**y = f(w₁x₁ + w₂x₂ + w₃x₃ + b)** + + + +### 激活函数：为什么需要非线性？ + +如果没有激活函数，无论多少层神经元叠加，最终都等价于一个线性变换（矩阵乘法）。激活函数引入**非线性**，让网络能学习复杂的模式。 + +| 激活函数 | 公式 | 特点 | 常用场景 | +|---------|------|------|---------| +| ReLU | max(0, x) | 简单高效，训练快 | 隐藏层的默认选择 | +| Sigmoid | 1/(1+e⁻ˣ) | 输出 0~1 | 二分类输出层 | +| Tanh | (eˣ-e⁻ˣ)/(eˣ+e⁻ˣ) | 输出 -1~1 | RNN 中常用 | +| Softmax | eˣᵢ/Σeˣⱼ | 输出概率分布 | 多分类输出层 | + +### 从神经元到网络 + +把多个神经元组织成**层**，多个层串联起来，就构成了神经网络： + +``` +输入层 隐藏层1 隐藏层2 输出层 +(特征) (提取低级特征) (提取高级特征) (预测结果) + + x1 ──→ [○ ○ ○ ○] ──→ [○ ○ ○] ──→ [○ ○] + x2 ──→ [○ ○ ○ ○] ──→ [○ ○ ○] ──→ 猫/狗 + x3 ──→ [○ ○ ○ ○] ──→ [○ ○ ○] +``` + +| 概念 | 说明 | +|------|------| +| 输入层 | 接收原始数据（图片像素、文本向量等） | +| 隐藏层 | 中间处理层，层数越多网络越"深"（深度学习的"深"） | +| 输出层 | 产生最终预测（分类概率、回归值等） | +| 前向传播 | 数据从输入层逐层流向输出层的过程 | + +::: tip 为什么叫"深度"学习？ +传统机器学习通常只有 1-2 层。当隐藏层数量增加到几十甚至上百层时，就叫"深度"学习。更深的网络能学习更抽象的特征：第一层学边缘，第二层学纹理，第三层学部件，更深的层学到"这是一只猫"。 +::: + +--- + +## 2. 网络如何学习 + +神经网络的"学习"本质上是一个**优化问题**：找到一组权重（w）和偏置（b），使得网络的预测尽可能接近真实答案。 + +### 训练三步曲 + +``` +1. 前向传播：输入数据，得到预测结果 +2. 计算损失：用损失函数衡量预测与真实值的差距 +3. 反向传播：根据损失，计算每个权重的梯度，更新权重 + ↓ +重复以上步骤，直到损失足够小 +``` + +### 损失函数：衡量"错得有多离谱" + +损失函数（Loss Function）量化了预测值和真实值之间的差距。训练的目标就是最小化损失。 + +| 损失函数 | 公式简述 | 适用场景 | +|---------|---------|---------| +| MSE（均方误差） | 预测值与真实值差的平方的均值 | 回归问题 | +| Cross-Entropy（交叉熵） | -Σ y·log(ŷ) | 分类问题 | +| Binary Cross-Entropy | 交叉熵的二分类版本 | 二分类问题 | + +### 梯度下降：找到最低点 + +想象你站在一座山上，蒙着眼睛要走到最低点。你能做的就是**摸一下脚下的坡度，然后往下坡方向走一步**。这就是梯度下降。 + +``` +损失值 + ↑ + │ ╱╲ + │ ╱ ╲ ← 当前位置 + │ ╱ ╲ ↙ 沿梯度方向下降 + │ ╱ ╲╱ ← 局部最小值 + │╱ ╲╱ ← 全局最小值 + └──────────────→ 权重值 +``` + +| 概念 | 说明 | +|------|------| +| 梯度 | 损失函数对每个权重的偏导数，指示"往哪个方向调整能减少损失" | +| 学习率 | 每一步走多远。太大会跳过最低点，太小会收敛太慢 | +| 批量大小 | 每次用多少样本计算梯度。全量太慢，单样本太抖，小批量（mini-batch）是折中 | + +### 反向传播：链式法则的胜利 + +反向传播（Backpropagation）是计算梯度的高效算法。它利用微积分的**链式法则**，从输出层开始，逐层向后计算每个权重对损失的贡献。 + +``` +前向传播：输入 → 隐藏层1 → 隐藏层2 → 输出 → 损失 +反向传播：损失 → 输出 → 隐藏层2 → 隐藏层1 → 更新所有权重 +``` + +::: tip 直觉理解反向传播 +把神经网络想象成一条流水线。产品（预测）出了问题（损失大），你需要从最后一道工序开始往回查，看每道工序（每层权重）对最终问题贡献了多少，然后按贡献大小调整。贡献大的多调，贡献小的少调。 +::: + +--- + +## 3. 主流网络架构 + +不同类型的数据需要不同的网络架构。选对架构，事半功倍。 + + + +### 3.1 CNN（卷积神经网络） + +CNN 是处理图像的王者。核心思想：用小的卷积核在图像上滑动，提取局部特征。 + +``` +输入图像 → [卷积层→激活→池化] × N → 全连接层 → 输出 + 28×28 提取边缘/纹理/形状 分类结果 +``` + +| 特点 | 说明 | +|------|------| +| 局部连接 | 每个神经元只看一小块区域，而非整张图 | +| 参数共享 | 同一个卷积核在整张图上复用，大幅减少参数 | +| 平移不变性 | 猫在图片左边还是右边，都能识别 | +| 层级特征 | 浅层学边缘，深层学语义 | + +代表模型：LeNet、AlexNet、VGG、ResNet、EfficientNet + +### 3.2 RNN（循环神经网络） + +RNN 专为**序列数据**设计。它的隐藏状态会传递到下一个时间步，让网络具有"记忆"能力。 + +``` +时间步 t1 时间步 t2 时间步 t3 + "我" ──→ "喜欢" ──→ "猫" + ↓ ↓ ↓ + [h1] ──→ [h2] ──→ [h3] ──→ 输出 + ↑ ↑ ↑ + 隐藏状态在时间步之间传递（记忆） +``` + +| 变体 | 解决的问题 | 核心机制 | +|------|-----------|---------| +| 原始 RNN | 基础序列建模 | 简单循环连接 | +| LSTM | 长序列梯度消失 | 遗忘门、输入门、输出门 | +| GRU | LSTM 参数太多 | 简化为重置门和更新门 | +| 双向 RNN | 只能看到过去 | 同时从前往后和从后往前处理 | + +::: tip LSTM 的门控机制 +LSTM 的精妙之处在于三个"门"：**遗忘门**决定丢弃哪些旧记忆，**输入门**决定存入哪些新信息，**输出门**决定输出哪些内容。就像你读一本书，会选择性地记住重要情节、忘掉无关细节。 +::: + +### 3.3 Transformer：注意力就是一切 + +2017 年 Google 发表的 "Attention Is All You Need" 论文提出了 Transformer，彻底改变了 AI 领域。它用**自注意力机制**替代了循环结构，是 GPT、BERT、Claude 等大模型的基础。 + +``` +输入序列 → 嵌入 + 位置编码 → [多头注意力 → 前馈网络] × N → 输出 + ↑ + 每个词都能"看到"所有其他词 +``` + +| 优势 | 说明 | +|------|------| +| 并行计算 | 不像 RNN 必须逐步处理，Transformer 可以并行处理整个序列 | +| 长距离依赖 | 任意两个位置之间直接建立联系，不受距离限制 | +| 可扩展性 | 模型越大、数据越多，效果越好（Scaling Law） | + +**自注意力的直觉**：读"小猫坐在垫子上，因为**它**很累"这句话时，"它"需要关注"小猫"才能理解含义。自注意力让模型学会这种关联——为序列中的每对词计算一个"相关性分数"。 + + + +## 4. 训练的艺术 + +有了好的架构还不够，训练过程中有很多"坑"需要避开。 + +### 4.1 过拟合 vs 欠拟合 + +| 问题 | 表现 | 原因 | 解决方案 | +|------|------|------|---------| +| 过拟合 | 训练集表现好，测试集表现差 | 模型太复杂，"背答案"而非学规律 | 正则化、Dropout、数据增强、早停 | +| 欠拟合 | 训练集和测试集都表现差 | 模型太简单，学不到规律 | 增加模型容量、训练更久、更好的特征 | + +``` +误差 + ↑ + │ ╲ 训练误差 测试误差 ╱ + │ ╲ ╱ + │ ╲─────────────────╱ + │ 欠拟合 ← 最佳点 → 过拟合 + └──────────────────────────→ 模型复杂度 +``` + +### 4.2 关键超参数 + +超参数是训练前需要人为设定的参数（不是模型自己学的）： + +| 超参数 | 作用 | 常见范围 | 调优建议 | +|--------|------|---------|---------| +| 学习率 | 每步更新的幅度 | 1e-5 ~ 1e-1 | 最重要的超参数，通常从 1e-3 开始 | +| 批量大小 | 每次训练用多少样本 | 16 ~ 512 | 越大训练越稳定，但需要更多显存 | +| 训练轮数（Epoch） | 遍历整个数据集的次数 | 10 ~ 100+ | 配合早停法，验证集不再提升就停 | +| 优化器 | 梯度更新策略 | Adam、SGD | Adam 是默认选择，SGD+动量适合精调 | + +### 4.3 正则化技巧 + +防止过拟合的常用手段： + +| 技巧 | 原理 | 使用方式 | +|------|------|---------| +| Dropout | 训练时随机关闭部分神经元 | 通常 p=0.1~0.5 | +| 权重衰减 | 在损失函数中加入权重大小的惩罚 | L2 正则化，λ=1e-4 | +| 数据增强 | 对训练数据做随机变换（翻转、裁剪、旋转） | 图像任务必备 | +| 早停法 | 验证集损失不再下降时停止训练 | patience=5~10 | +| Batch Normalization | 标准化每层的输入分布 | 加速收敛，有轻微正则化效果 | + +::: tip 训练的经验法则 +1. 先用小数据集跑通整个流程，确认代码没 bug +2. 从已有的预训练模型开始微调，而非从零训练 +3. 学习率是最值得花时间调的超参数 +4. 如果训练损失不下降，先检查数据和代码，再怀疑模型 +::: + +--- + +## 5. 发展历程与前沿 + +神经网络的发展经历了几次"寒冬"和"复兴"，每次突破都源于关键的技术创新。 + +| 年代 | 里程碑 | 关键突破 | +|------|--------|---------| +| 1958 | 感知机（Perceptron） | 第一个神经网络模型，只能处理线性问题 | +| 1986 | 反向传播算法 | 让多层网络的训练成为可能 | +| 1998 | LeNet（CNN） | 卷积网络在手写数字识别上大获成功 | +| 2012 | AlexNet | 深度 CNN 在 ImageNet 上碾压传统方法，深度学习爆发 | +| 2014 | GAN（生成对抗网络） | 两个网络对抗训练，能生成逼真图像 | +| 2017 | Transformer | "Attention Is All You Need"，注意力机制取代 RNN | +| 2018 | BERT | 预训练+微调范式，NLP 全面突破 | +| 2020 | GPT-3 | 1750 亿参数，展示了大模型的涌现能力 | +| 2022 | ChatGPT | RLHF 对齐技术，AI 进入大众视野 | +| 2023+ | 多模态大模型 | GPT-4V、Claude 等，同时理解文本和图像 | + +### 当前趋势 + +| 方向 | 说明 | +|------|------| +| 大模型（LLM） | 参数量从亿级到万亿级，涌现出推理、编程等能力 | +| 多模态 | 同一个模型处理文本、图像、音频、视频 | +| 高效微调 | LoRA、QLoRA 等技术让普通开发者也能微调大模型 | +| AI Agent | 让大模型使用工具、规划任务、自主完成复杂目标 | +| 小模型蒸馏 | 用大模型的知识训练小模型，在端侧部署 | + +::: tip 对开发者的启示 +你不需要从零训练神经网络。现代 AI 开发更多是**调用 API**（如 OpenAI、Claude API）或**微调预训练模型**（如用 Hugging Face）。但理解底层原理能帮你更好地选择模型、设计 prompt、诊断问题。 +::: + +--- + +## 总结 + +| 核心概念 | 一句话总结 | +|---------|-----------| +| 神经元 | 加权求和 + 激活函数，网络的最小计算单元 | +| 前向传播 | 数据从输入层逐层流向输出层，产生预测 | +| 反向传播 | 从损失出发，逐层计算梯度，更新权重 | +| CNN | 卷积核提取局部特征，图像处理的首选 | +| RNN/LSTM | 循环连接保持记忆，处理序列数据 | +| Transformer | 自注意力并行处理，大模型的基础架构 | +| 过拟合 | 模型"背答案"，用正则化、Dropout 等手段防止 | +| 迁移学习 | 站在巨人肩膀上，用预训练模型微调解决新问题 | + +--- + +## 延伸阅读 + +- [3Blue1Brown - 神经网络系列视频](https://www.3blue1brown.com/topics/neural-networks) — 最直观的可视化讲解 +- [Stanford CS231n](http://cs231n.stanford.edu/) — 经典的卷积神经网络课程 +- [The Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/) — 图解 Transformer 架构 +- [Neural Networks and Deep Learning](http://neuralnetworksanddeeplearning.com/) — 免费在线教材 +- [Hugging Face 课程](https://huggingface.co/learn) — 动手实践 Transformer 和大模型 diff --git a/docs/zh-cn/appendix/index.md b/docs/zh-cn/appendix/index.md index 4c7b8be..2741428 100644 --- a/docs/zh-cn/appendix/index.md +++ b/docs/zh-cn/appendix/index.md @@ -2,6 +2,14 @@ 本附录涵盖从计算机基础到工程素养的完整知识体系，是你学习旅程中的重要参考库。 +## 📍 附录知识地图 + +点击下方的分类卡片，查看每个分类的完整学习路径： + + + +--- + ## 内容分类 ### 一、计算机是怎么回事 diff --git a/find-intervals.mjs b/find-intervals.mjs new file mode 100644 index 0000000..28acd53 --- /dev/null +++ b/find-intervals.mjs @@ -0,0 +1,28 @@ +import fs from 'fs' +import path from 'path' + +function walkSync(dir, filelist = []) { + fs.readdirSync(dir).forEach(file => { + const dirFile = path.join(dir, file) + try { + filelist = fs.statSync(dirFile).isDirectory() ? walkSync(dirFile, filelist) : filelist.concat(dirFile) + } catch (err) { + if (err.code === 'OOM' || err.code === 'EMFILE') throw err + } + }) + return filelist +} + +const vueFiles = walkSync('docs/.vitepress/theme/components').filter(f => f.endsWith('.vue')) + +for (const file of vueFiles) { + const content = fs.readFileSync(file, 'utf8') + if (content.includes('setInterval')) { + const lines = content.split('\n') + lines.forEach((line, i) => { + if (line.includes('setInterval')) { + console.log(`${file}:${i + 1}: ${line.trim()}`) + } + }) + } +} diff --git a/find_setinterval.cjs b/find_setinterval.cjs new file mode 100644 index 0000000..665d3d5 --- /dev/null +++ b/find_setinterval.cjs @@ -0,0 +1,52 @@ +const fs = require('fs'); +const path = require('path'); + +function walk(dir) { + let results = []; + const list = fs.readdirSync(dir); + list.forEach(function (file) { + file = dir + '/' + file; + const stat = fs.statSync(file); + if (stat && stat.isDirectory()) { + results = results.concat(walk(file)); + } else { + if (file.endsWith('.vue')) results.push(file); + } + }); + return results; +} + +const vueFiles = walk('docs/.vitepress/theme/components'); + +vueFiles.forEach(file => { + const lines = fs.readFileSync(file, 'utf8').split('\n'); + let bracketDepth = 0; + let insideScript = false; + + lines.forEach((line, index) => { + if (line.includes('