+
+
+
diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js
index 87d5e26..2a7db45 100644
--- a/docs/.vitepress/theme/index.js
+++ b/docs/.vitepress/theme/index.js
@@ -710,7 +710,10 @@ import DecisionMatrixDemo from './components/appendix/engineering-excellence/Dec
import SqlDemo from './components/appendix/data/SqlDemo.vue'
import DataModelsDemo from './components/appendix/data/DataModelsDemo.vue'
import ABTestingDemo from './components/appendix/data/ABTestingDemo.vue'
-import DataAnalysisDemo from './components/appendix/data/DataAnalysisDemo.vue'
+import DescriptiveStatsDemo from './components/appendix/data/DescriptiveStatsDemo.vue'
+import DataAggregationDemo from './components/appendix/data/DataAggregationDemo.vue'
+import FunnelAnalysisDemo from './components/appendix/data/FunnelAnalysisDemo.vue'
+import RetentionAnalysisDemo from './components/appendix/data/RetentionAnalysisDemo.vue'
import DataTrackingDemo from './components/appendix/data/DataTrackingDemo.vue'
// RAG Components
@@ -1542,7 +1545,10 @@ export default {
app.component('SqlDemo', SqlDemo)
app.component('DataModelsDemo', DataModelsDemo)
app.component('ABTestingDemo', ABTestingDemo)
- app.component('DataAnalysisDemo', DataAnalysisDemo)
+ app.component('DescriptiveStatsDemo', DescriptiveStatsDemo)
+ app.component('DataAggregationDemo', DataAggregationDemo)
+ app.component('FunnelAnalysisDemo', FunnelAnalysisDemo)
+ app.component('RetentionAnalysisDemo', RetentionAnalysisDemo)
app.component('DataTrackingDemo', DataTrackingDemo)
// Engineering Excellence Components Registration
@@ -1673,7 +1679,10 @@ export default {
app.component('NetworkArchitectureDemo', NetworkArchitectureDemo)
// Project Architecture Components Registration
- app.component('ProjectArchitectureComparisonDemo', ProjectArchitectureComparisonDemo)
+ app.component(
+ 'ProjectArchitectureComparisonDemo',
+ ProjectArchitectureComparisonDemo
+ )
// Appendix Navigation Component Registration
app.component('AppendixFlowMap', AppendixFlowMap)
diff --git a/docs/.vitepress/theme/locales/ai-history/en.js b/docs/.vitepress/theme/locales/ai-history/en.js
index 191b6b2..709f798 100644
--- a/docs/.vitepress/theme/locales/ai-history/en.js
+++ b/docs/.vitepress/theme/locales/ai-history/en.js
@@ -48,13 +48,45 @@ export default {
foundation: {
label: 'Core idea of Symbolism — encoding knowledge as rules',
lines: [
- { parts: [{ kw: 'IF' }, { text: ' temperature > 38.5°C ' }, { kw: 'AND' }, { text: ' WBC count > 11000' }] },
- { indent: true, parts: [{ kw: 'THEN' }, { text: ' diagnosis = ' }, { str: '"bacterial infection"' }] },
- { parts: [{ kw: 'IF' }, { text: ' diagnosis = ' }, { str: '"bacterial infection"' }, { text: ' ' }, { kw: 'AND' }, { text: ' no penicillin allergy' }] },
- { indent: true, parts: [{ kw: 'THEN' }, { text: ' treatment = ' }, { str: '"penicillin 400mg / twice daily"' }] }
+ {
+ parts: [
+ { kw: 'IF' },
+ { text: ' temperature > 38.5°C ' },
+ { kw: 'AND' },
+ { text: ' WBC count > 11000' }
+ ]
+ },
+ {
+ indent: true,
+ parts: [
+ { kw: 'THEN' },
+ { text: ' diagnosis = ' },
+ { str: '"bacterial infection"' }
+ ]
+ },
+ {
+ parts: [
+ { kw: 'IF' },
+ { text: ' diagnosis = ' },
+ { str: '"bacterial infection"' },
+ { text: ' ' },
+ { kw: 'AND' },
+ { text: ' no penicillin allergy' }
+ ]
+ },
+ {
+ indent: true,
+ parts: [
+ { kw: 'THEN' },
+ { text: ' treatment = ' },
+ { str: '"penicillin 400mg / twice daily"' }
+ ]
+ }
],
- comment: '// The early medical expert system MYCIN (1977) consisted of 450+ rules like these',
- caption: 'Human experts translate experience into IF-THEN rules; the machine matches and executes them one by one'
+ comment:
+ '// The early medical expert system MYCIN (1977) consisted of 450+ rules like these',
+ caption:
+ 'Human experts translate experience into IF-THEN rules; the machine matches and executes them one by one'
},
// PerceptronDemo
@@ -63,16 +95,33 @@ export default {
biasLabel: 'Bias',
activated: 'Fire',
silent: 'Silent',
- caption: '① Input features\u2003② Multiply by weights (importance)\u2003③ Sum + bias\u2003④ Fires output 1 if above threshold, otherwise 0'
+ caption:
+ '① Input features\u2003② Multiply by weights (importance)\u2003③ Sum + bias\u2003④ Fires output 1 if above threshold, otherwise 0'
},
// BackpropagationDemo
backprop: {
steps: [
- { icon: '➡️', name: 'Forward Pass', desc: 'Data flows through the network to produce a prediction' },
- { icon: '📐', name: 'Compute Loss', desc: 'Prediction vs. ground truth → calculate loss' },
- { icon: '⬅️', name: 'Backpropagation', desc: 'Trace back each weight\'s "responsibility" layer by layer' },
- { icon: '⚙️', name: 'Update Weights', desc: 'Adjust proportionally to reduce future error' }
+ {
+ icon: '➡️',
+ name: 'Forward Pass',
+ desc: 'Data flows through the network to produce a prediction'
+ },
+ {
+ icon: '📐',
+ name: 'Compute Loss',
+ desc: 'Prediction vs. ground truth → calculate loss'
+ },
+ {
+ icon: '⬅️',
+ name: 'Backpropagation',
+ desc: 'Trace back each weight\'s "responsibility" layer by layer'
+ },
+ {
+ icon: '⚙️',
+ name: 'Update Weights',
+ desc: 'Adjust proportionally to reduce future error'
+ }
],
lossLabel: 'Loss decreases over training epochs:',
axisHigh: 'High',
@@ -84,7 +133,10 @@ export default {
neuralNet: {
layers: [
{ name: 'Input Layer', desc: 'Raw pixels / numerical signals' },
- { name: 'Hidden Layers (stackable)', desc: 'Low → edges; Mid → shapes; High → semantic concepts' },
+ {
+ name: 'Hidden Layers (stackable)',
+ desc: 'Low → edges; Mid → shapes; High → semantic concepts'
+ },
{ name: 'Output Layer', desc: 'Final classification or prediction' }
]
},
@@ -94,16 +146,41 @@ export default {
colLabel: 'Attention distribution when processing "{word}":',
sentence: ['John', 'gave', 'the', 'apple', 'to', 'his', 'mother'],
focusIdx: 5,
- weights: [0.62, 0.08, 0.03, 0.10, 0.05, 0.07, 0.05],
- caption: '"his" sits mid-sentence, yet the model directs 62% attention to "John" at the start — resolving the pronoun across distance'
+ weights: [0.62, 0.08, 0.03, 0.1, 0.05, 0.07, 0.05],
+ caption:
+ '"his" sits mid-sentence, yet the model directs 62% attention to "John" at the start — resolving the pronoun across distance'
},
// GPTEvolutionDemo
gptEvolution: [
- { name: 'GPT-1', year: '2018', params: '117 M', barWidth: '2%', key: 'Pre-train + fine-tune paradigm' },
- { name: 'GPT-2', year: '2019', params: '1.5 B', barWidth: '6%', key: 'Zero-shot generalization' },
- { name: 'GPT-3', year: '2020', params: '175 B', barWidth: '45%', key: '⚡ Emergence! In-context learning' },
- { name: 'GPT-4', year: '2023', params: '~1.8 T', barWidth: '100%', key: 'Multimodal + complex reasoning' }
+ {
+ name: 'GPT-1',
+ year: '2018',
+ params: '117 M',
+ barWidth: '2%',
+ key: 'Pre-train + fine-tune paradigm'
+ },
+ {
+ name: 'GPT-2',
+ year: '2019',
+ params: '1.5 B',
+ barWidth: '6%',
+ key: 'Zero-shot generalization'
+ },
+ {
+ name: 'GPT-3',
+ year: '2020',
+ params: '175 B',
+ barWidth: '45%',
+ key: '⚡ Emergence! In-context learning'
+ },
+ {
+ name: 'GPT-4',
+ year: '2023',
+ params: '~1.8 T',
+ barWidth: '100%',
+ key: 'Multimodal + complex reasoning'
+ }
],
// AIErasComparisonDemo
@@ -113,11 +190,41 @@ export default {
mechanismLabel: 'Core Mechanism',
examplesLabel: 'Key Examples',
eras: [
- { name: 'Rule-Based Era', time: '1960s - 1980s', driver: 'Human-coded knowledge', mechanism: 'If-Then logical deduction', examples: ['Dendral', 'Deep Blue'] },
- { name: 'Classical ML', time: '1990s - 2000s', driver: 'Manual feature engineering + statistics', mechanism: 'Finding mathematical decision boundaries', examples: ['SVM', 'Random Forest'] },
- { name: 'Deep Learning Revolution', time: '2010s', driver: 'Big data + GPU compute', mechanism: 'Neural nets auto-extract features', examples: ['AlexNet (CNN)', 'AlphaGo (RL)'] },
- { name: 'Large Language Models', time: '2018 - present', driver: 'Massive unlabeled data + brute-force compute', mechanism: 'Next-token prediction + emergent knowledge', examples: ['GPT-4', 'Claude 3'] },
- { name: 'Agentic AI', time: 'Now - future', driver: 'LLM brain + environment perception', mechanism: 'Autonomous planning + tool use', examples: ['AI Programmer', 'Embodied AI'] }
+ {
+ name: 'Rule-Based Era',
+ time: '1960s - 1980s',
+ driver: 'Human-coded knowledge',
+ mechanism: 'If-Then logical deduction',
+ examples: ['Dendral', 'Deep Blue']
+ },
+ {
+ name: 'Classical ML',
+ time: '1990s - 2000s',
+ driver: 'Manual feature engineering + statistics',
+ mechanism: 'Finding mathematical decision boundaries',
+ examples: ['SVM', 'Random Forest']
+ },
+ {
+ name: 'Deep Learning Revolution',
+ time: '2010s',
+ driver: 'Big data + GPU compute',
+ mechanism: 'Neural nets auto-extract features',
+ examples: ['AlexNet (CNN)', 'AlphaGo (RL)']
+ },
+ {
+ name: 'Large Language Models',
+ time: '2018 - present',
+ driver: 'Massive unlabeled data + brute-force compute',
+ mechanism: 'Next-token prediction + emergent knowledge',
+ examples: ['GPT-4', 'Claude 3']
+ },
+ {
+ name: 'Agentic AI',
+ time: 'Now - future',
+ driver: 'LLM brain + environment perception',
+ mechanism: 'Autonomous planning + tool use',
+ examples: ['AI Programmer', 'Embodied AI']
+ }
]
}
}
diff --git a/docs/.vitepress/theme/locales/ai-history/zh-cn.js b/docs/.vitepress/theme/locales/ai-history/zh-cn.js
index 25f49bb..d1a6895 100644
--- a/docs/.vitepress/theme/locales/ai-history/zh-cn.js
+++ b/docs/.vitepress/theme/locales/ai-history/zh-cn.js
@@ -48,10 +48,36 @@ export default {
foundation: {
label: '符号主义的核心思路 ── 把知识写成规则',
lines: [
- { parts: [{ kw: 'IF' }, { text: ' 体温 > 38.5°C ' }, { kw: 'AND' }, { text: ' 白细胞计数 > 11000' }] },
- { indent: true, parts: [{ kw: 'THEN' }, { text: ' 诊断 = ' }, { str: '"细菌感染"' }] },
- { parts: [{ kw: 'IF' }, { text: ' 诊断 = ' }, { str: '"细菌感染"' }, { text: ' ' }, { kw: 'AND' }, { text: ' 对青霉素不过敏' }] },
- { indent: true, parts: [{ kw: 'THEN' }, { text: ' 治疗方案 = ' }, { str: '"青霉素 400mg / 每日两次"' }] }
+ {
+ parts: [
+ { kw: 'IF' },
+ { text: ' 体温 > 38.5°C ' },
+ { kw: 'AND' },
+ { text: ' 白细胞计数 > 11000' }
+ ]
+ },
+ {
+ indent: true,
+ parts: [{ kw: 'THEN' }, { text: ' 诊断 = ' }, { str: '"细菌感染"' }]
+ },
+ {
+ parts: [
+ { kw: 'IF' },
+ { text: ' 诊断 = ' },
+ { str: '"细菌感染"' },
+ { text: ' ' },
+ { kw: 'AND' },
+ { text: ' 对青霉素不过敏' }
+ ]
+ },
+ {
+ indent: true,
+ parts: [
+ { kw: 'THEN' },
+ { text: ' 治疗方案 = ' },
+ { str: '"青霉素 400mg / 每日两次"' }
+ ]
+ }
],
comment: '// 早期医疗专家系统（MYCIN，1977）就是由 450+ 条这样的规则组成的',
caption: '人类专家把经验翻译成一条条 IF-THEN 规则，机器逐条匹配执行'
@@ -63,7 +89,8 @@ export default {
biasLabel: '偏置',
activated: '激活',
silent: '静默',
- caption: '① 输入特征\u2003② 乘以权重（重要性）\u2003③ 求和 + 偏置\u2003④ 超过阈值就激活输出 1，否则输出 0'
+ caption:
+ '① 输入特征\u2003② 乘以权重（重要性）\u2003③ 求和 + 偏置\u2003④ 超过阈值就激活输出 1，否则输出 0'
},
// BackpropagationDemo
@@ -84,7 +111,10 @@ export default {
neuralNet: {
layers: [
{ name: '输入层', desc: '原始像素 / 数值信号' },
- { name: '隐藏层（可叠加多层）', desc: '底层识别边缘 → 中层识别形状 → 高层识别语义概念' },
+ {
+ name: '隐藏层（可叠加多层）',
+ desc: '底层识别边缘 → 中层识别形状 → 高层识别语义概念'
+ },
{ name: '输出层', desc: '最终分类或预测结果' }
]
},
@@ -94,16 +124,41 @@ export default {
colLabel: '处理「{word}」时的注意力分配：',
sentence: ['小明', '把', '苹果', '给了', '他', '的', '母亲'],
focusIdx: 4,
- weights: [0.65, 0.05, 0.10, 0.10, 0.05, 0.03, 0.02],
- caption: '「他」虽在句中间，模型却把 65% 注意力精准投向句首的「小明」，跨越距离识别代词指代'
+ weights: [0.65, 0.05, 0.1, 0.1, 0.05, 0.03, 0.02],
+ caption:
+ '「他」虽在句中间，模型却把 65% 注意力精准投向句首的「小明」，跨越距离识别代词指代'
},
// GPTEvolutionDemo
gptEvolution: [
- { name: 'GPT-1', year: '2018', params: '1.17 亿', barWidth: '2%', key: '预训练+微调范式确立' },
- { name: 'GPT-2', year: '2019', params: '15 亿', barWidth: '6%', key: 'Zero-shot 零样本泛化' },
- { name: 'GPT-3', year: '2020', params: '1750 亿', barWidth: '45%', key: '⚡ 涌现！上下文学习' },
- { name: 'GPT-4', year: '2023', params: '~1.8 万亿', barWidth: '100%', key: '多模态 + 复杂推理' }
+ {
+ name: 'GPT-1',
+ year: '2018',
+ params: '1.17 亿',
+ barWidth: '2%',
+ key: '预训练+微调范式确立'
+ },
+ {
+ name: 'GPT-2',
+ year: '2019',
+ params: '15 亿',
+ barWidth: '6%',
+ key: 'Zero-shot 零样本泛化'
+ },
+ {
+ name: 'GPT-3',
+ year: '2020',
+ params: '1750 亿',
+ barWidth: '45%',
+ key: '⚡ 涌现！上下文学习'
+ },
+ {
+ name: 'GPT-4',
+ year: '2023',
+ params: '~1.8 万亿',
+ barWidth: '100%',
+ key: '多模态 + 复杂推理'
+ }
],
// AIErasComparisonDemo
@@ -113,11 +168,41 @@ export default {
mechanismLabel: '核心机制',
examplesLabel: '典型代表',
eras: [
- { name: '规则系统时代', time: '1960s - 1980s', driver: '人类硬编码知识', mechanism: 'If-Then 逻辑推演', examples: ['Dendral', '深蓝 (Deep Blue)'] },
- { name: '传统机器学习', time: '1990s - 2000s', driver: '人工特征工程 + 统计学', mechanism: '寻找数学决策边界', examples: ['支持向量机 (SVM)', '随机森林'] },
- { name: '深度学习革命', time: '2010s', driver: '大数据 + 算力爬升', mechanism: '神经网络自动提取特征', examples: ['AlexNet (CNN)', 'AlphaGo (RL)'] },
- { name: '大语言模型 (LLM)', time: '2018 - 至今', driver: '海量无标注数据 + 暴力计算', mechanism: '预测下一个词 + 涌现常识', examples: ['GPT-4', 'Claude 3'] },
- { name: '智能体 (Agentic AI)', time: '现在 - 未来', driver: '大模型大脑 + 环境感知', mechanism: '自主规划 + 工具调用', examples: ['AI 程序员', '具身智能'] }
+ {
+ name: '规则系统时代',
+ time: '1960s - 1980s',
+ driver: '人类硬编码知识',
+ mechanism: 'If-Then 逻辑推演',
+ examples: ['Dendral', '深蓝 (Deep Blue)']
+ },
+ {
+ name: '传统机器学习',
+ time: '1990s - 2000s',
+ driver: '人工特征工程 + 统计学',
+ mechanism: '寻找数学决策边界',
+ examples: ['支持向量机 (SVM)', '随机森林']
+ },
+ {
+ name: '深度学习革命',
+ time: '2010s',
+ driver: '大数据 + 算力爬升',
+ mechanism: '神经网络自动提取特征',
+ examples: ['AlexNet (CNN)', 'AlphaGo (RL)']
+ },
+ {
+ name: '大语言模型 (LLM)',
+ time: '2018 - 至今',
+ driver: '海量无标注数据 + 暴力计算',
+ mechanism: '预测下一个词 + 涌现常识',
+ examples: ['GPT-4', 'Claude 3']
+ },
+ {
+ name: '智能体 (Agentic AI)',
+ time: '现在 - 未来',
+ driver: '大模型大脑 + 环境感知',
+ mechanism: '自主规划 + 工具调用',
+ examples: ['AI 程序员', '具身智能']
+ }
]
}
}
diff --git a/docs/en/appendix/2-development-tools/editors-and-ai/images/image23.png b/docs/en/appendix/2-development-tools/editors-and-ai/images/image23.png
new file mode 100644
index 0000000..afadf2e
Binary files /dev/null and b/docs/en/appendix/2-development-tools/editors-and-ai/images/image23.png differ
diff --git a/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-28-43.png b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-28-43.png
new file mode 100644
index 0000000..d1d39d8
Binary files /dev/null and b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-28-43.png differ
diff --git a/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-35-55.png b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-35-55.png
new file mode 100644
index 0000000..dc1119f
Binary files /dev/null and b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-35-55.png differ
diff --git a/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-36-23.png b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-36-23.png
new file mode 100644
index 0000000..4451de0
Binary files /dev/null and b/docs/en/appendix/2-development-tools/editors-and-ai/images/index-2026-01-09-11-36-23.png differ
diff --git a/docs/en/appendix/2-development-tools/ide-basics.md b/docs/en/appendix/2-development-tools/ide-basics.md
new file mode 100644
index 0000000..c04a3ea
--- /dev/null
+++ b/docs/en/appendix/2-development-tools/ide-basics.md
@@ -0,0 +1,312 @@
+# Integrated Development Environment (IDE) Basics
+
+::: tip 💡 Learning Guide
+This chapter will take you deep into the core productivity tool for programmers—the **Integrated Development Environment (IDE)**. We'll start from the design philosophy of IDEs, analyze their core components one by one, and demonstrate their working principles through a virtual IDE.
+:::
+
+## What to Do When You Don't Understand Something? (How to solve problems)
+
+In the process of learning and using an IDE, you may encounter various buttons, menus, or code errors that you don't understand. At this time, **don't panic—using an AI assistant is the most efficient solution**.
+
+**Recommended Approach: Screenshot and Ask AI**
+
+Modern AIs (such as ChatGPT, Claude, DeepSeek, etc.) have powerful image recognition capabilities. When you encounter unfamiliar interface elements or complex code snippets:
+
+1. **Screenshot**: Capture the part you don't understand (such as a strange icon or a complex configuration code).
+2. **Ask**: Send the image to AI and ask: "What is this? What's it for?" or "What does xxx do in this code?"
+3. **Follow up**: If AI's answer is too technical to understand, continue asking: "Please explain it in plain language, preferably with a real-life example."
+
+
+
+---
+
+## 0. Introduction: Why Do We Need an IDE?
+
+In the software development process, programmers need to frequently write code, manage files, compile and run programs, debug errors, and so on. If all these operations needed to be completed in different independent software (for example, using Notepad to write code, command line to compile, and file folders to manage files), efficiency would be extremely low and error-prone.
+
+The core value of an **IDE (Integrated Development Environment)** lies in **integration**. It integrates various tools needed for software development (editor, compiler, debugger, file manager, etc.) into a unified graphical interface, providing a one-stop working experience.
+
+**VS Code is one of the most popular IDEs.** Although it is essentially a lightweight code editor, through its powerful plugin system, it has all the core functions of an IDE (code editing, debugging, version control, etc.), and is therefore widely regarded as the preferred IDE for modern frontend and full-stack development.
+
+In short, IDEs aim to maximize developer productivity and reduce the time cost of switching between different tools.
+
+> 🔗 **Resource Downloads**:
+>
+> - [VS Code Official Download](https://code.visualstudio.com/Download)
+> - [VS Code Web Version Experience](https://vscode.dev/)
+>
+> **VS Code (Visual Studio Code)** is a free, open-source, cross-platform code editor developed by Microsoft. With its **lightweight nature, rich plugins, and fast startup speed**, it has become one of the most popular development tools worldwide. Whether you're writing Python, JavaScript, or C++, VS Code can become the most suitable "tool" for you through plugin installation.
+
+---
+
+## 1. Core Interface Analysis
+
+The interface layout of modern IDEs (taking VS Code as an example) has been carefully designed and usually contains the following four core areas:
+
+1. **Sidebar: Resource Management**
+ Displays the project's file tree, supports creating, renaming, moving, and deleting files, providing a global view and quick access to the project structure.
+
+2. **Editor Area: Code Creation**
+ The core area for writing and modifying code. Supports syntax highlighting, intelligent code completion, syntax checking, and other functions, providing an efficient and intelligent code writing environment.
+
+3. **Bottom Panel: Execution and Feedback**
+ Interacts with the underlying system and views running results. Includes Terminal, Output, etc., used for executing commands, viewing logs, and debugging.
+
+4. **Activity Bar: Function Navigation**
+ Located on the far left of the interface, containing icons for file explorer, search, Git management, etc., used to quickly switch between different work contexts (such as "writing code" and "submitting code").
+
+---
+
+## 2. Interactive Demo: Functional Experience
+
+Seeing is believing. To let you truly feel the convenience of an IDE, we have prepared a **virtual VS Code environment** for you.
+
+**Please try the following operations**:
+
+1. Click the **"▶ Start Auto Tour"** button in the upper right corner to follow the cursor and learn about each area.
+2. **Free Exploration**: Click the icons on the left to switch views, or click file names to open code.
+3. **Experience Integration**: You'll find that file management, code editing, and terminal running are all seamlessly connected within the same window.
+4. **Install Plugins**: Select **"Extensions Installation"** mode from the dropdown menu to experience how to install Python plugins in a virtual store.
+
+
+
+
+
+---
+
+## 3. Core Mechanism: Why Can VS Code Do Everything?
+
+You might be curious: Why can the same software write Python, C++, and do web development? How does it do it?
+Actually, VS Code's design philosophy can be summarized in one sentence: **"Minimalist core, pluggable capabilities."**
+
+### 3.1 Minimalist Core: Just a "Canvas"
+
+Imagine, the VS Code you just downloaded, if no plugins are installed, actually **doesn't understand programming**.
+At this point, it is essentially just a **powerful text editor**.
+
+- It is responsible for displaying text (rendering).
+- It is responsible for managing files (IO).
+- But it doesn't know that `print("Hello")` is Python code, nor does it know that `int main()` is a C++ entry point.
+
+### 3.2 Plugin System: Injecting "Soul"
+
+To make VS Code able to "understand" code, we need to install **Extensions**.
+Plugins are like specialized **translators**:
+
+- **Python Plugin**: Tells VS Code what variables are, what functions are, and how to run `.py` files.
+- **C++ Plugin**: Tells VS Code how to call the compiler and how to debug memory.
+
+This design makes VS Code very lightweight—if you don't write Java, you don't have to carry Java's runtime environment.
+
+### 3.3 Behind the Scenes: From Code to Execution
+
+
+
+
+
+Let's look at how VS Code, plugins, and the underlying environment collaborate through a specific scenario.
+Suppose you write a line of Python code and click **Run** or **Debug**:
+
+#### 1. Language Recognition (Activation)
+
+VS Code detects the `.py` suffix and automatically wakes up the **Python Plugin**. The plugin immediately takes over the editor, begins syntax analysis, colors the code differently (syntax highlighting), and provides intelligent suggestions.
+
+#### 2. Task Delegation (Delegation)
+
+When you issue a command, the plugin itself does not directly execute the code, but **delegates** the task to underlying professional tools:
+
+- **Run Mode**: The plugin generates a command (such as `python main.py`) and sends it to the system's **terminal** for execution.
+- **Debug Mode**: The plugin starts a **Debug Adapter**. It's like a "monitoring probe," connecting to the internals of the Python interpreter, allowing you to control code execution line by line.
+
+#### 3. Result Feedback (Feedback)
+
+The Python interpreter (or compiler) executes the code and returns the results (or error messages) to the plugin. The plugin then "carries" this information back and displays it in VS Code's **bottom terminal panel**.
+
+### 3.4 Summary: Using a "Restaurant" as an Analogy
+
+If the above formula is a bit abstract, we can imagine the process of writing code as **dining at a restaurant**:
+
+1. **VS Code is the "Restaurant Lobby"**:
+ - The decoration is luxurious and the environment is comfortable (code highlighting, beautiful themes).
+ - **But the lobby itself doesn't produce food**. You sit here just to more comfortably "order" (write code).
+
+2. **Environment (Python/Node) is the "Kitchen"**:
+ - This is where the real **cooking (running code)** happens.
+ - If the restaurant has no kitchen (Python not installed), you can sit in the lobby until dark and still won't get food.
+
+3. **Plugins are the "Waiters"**:
+ - They connect the lobby and the kitchen.
+ - They understand your menu, run to tell the kitchen: "Table 3 wants a 'run main.py'!"
+ - When it's done, they bring the results (steaming hot food) back to you.
+
+**Conclusion**:
+
+- Only installing VS Code = **Only lobby, no kitchen** (can only look, can't eat).
+- Only installing Python = **Only kitchen, no lobby** (can eat, but have to squat on the kitchen floor, poor experience).
+- **Installing VS Code + Plugins + Python = Perfect dining experience.**
+
+---
+
+
+
+# Appendix: Visual Studio Code Menu Bar Analysis
+
+To help everyone understand the meaning of each option, here we provide an in-depth analysis of the menu bar:
+
+
+
+
+
+
+ File: Project and File Open/Save/Workspace Management
+
+This menu is mainly responsible for: **Creating/Opening Files**, **Opening Project Folders**, **Managing Workspaces**, **Saving and Closing**.
+
+> The most commonly used are: Open Folder to open a project; Open… to open a single file; then use Save / Save All to save changes, and finally use Close Editor / Close Folder to end the current work. Workspace-related content can be slowly learned as you get more projects, no need to understand everything at once.
+
+- **New Text File**: Create a new unnamed text buffer for temporary notes or quick pasting.
+- **New File…**: Create a new file in the project (usually asks you to choose path/name).
+- **New Window**: Open a new VS Code window instance.
+- **New Window with Profile**: Open a new window with a specified Profile (extension/settings combination), suitable for isolating environments for different courses/projects.
+- **Open…**: Open a single file for editing.
+- **Open Folder…**: Open a folder as the project root directory (the most commonly used "open project" method).
+- **Open Workspace from File…**: Open a `.code-workspace` file to load a workspace with multiple folders/specific settings.
+- **Open Recent**: Quickly access recently opened files/folders/workspaces.
+- **Add Folder to Workspace…**: Add another folder to the current workspace (forming a multi-root workspace).
+- **Save Workspace As…**: Save the current workspace structure as a `.code-workspace` file for easy sharing/reuse.
+- **Duplicate Workspace**: Duplicate the current workspace configuration (commonly used to create similar project environments).
+- **Save**: Save changes to the current file.
+- **Save As…**: Save the current file with a new name/path.
+- **Save All**: Save all opened files that have modifications.
+- **Share**: Entry related to sharing/collaboration (specific content depends on version and extensions).
+- **Auto Save**: Toggle auto-save strategy (e.g., delayed save/focus change save).
+- **Revert File**: Discard unsaved changes to the current file and revert to the disk version.
+- **Close Editor**: Close the current tab.
+- **Close Folder**: Close the current project folder (workspace becomes empty).
+- **Close Window**: Close the current VS Code window.
+
+
+
+
+ Edit: Basic Editing, Find/Replace, Comments and Quick Edit Actions
+
+This menu is mainly responsible for: **Undo/Redo**, **Cut/Copy/Paste**, **Find/Replace**, **Comments and Editor Actions** (improving editing efficiency).
+
+- **Undo / Redo**: The most basic operations for when you write code wrong.
+- **Cut / Copy / Paste**: Text transportation.
+- **Find / Replace**: Search or batch modify in the current file.
+- **Find in Files / Replace in Files**: Global (whole project) search and replace, very powerful but use with caution.
+- **Toggle Line Comment**: `Ctrl + /`, quickly comment/uncomment the current line.
+- **Toggle Block Comment**: `Shift + Alt + A`, quickly comment/uncomment the selected area.
+- **Emmet: Expand Abbreviation**: A powerful tool for HTML/CSS development, type shorthand and press Tab to expand code.
+
+
+
+
+ Selection: Multi-cursor and Smart Selection
+
+This menu is mainly responsible for: **Cursor Control**, **Multi-line Editing**, **Expand/Shrink Selection**. This is VS Code's killer feature for improving efficiency.
+
+- **Select All**: Select all content in the current file.
+- **Expand Selection / Shrink Selection**: Intelligently perceive syntax structure, gradually expand or shrink the selection range (e.g., word -> string -> inside parentheses -> whole line -> function body).
+- **Copy Line Up / Down**: Quickly clone the current line.
+- **Move Line Up / Down**: `Alt + ↑ / ↓`, adjust code line order directly without cut and paste.
+- **Add Cursor Above / Below**: `Ctrl + Alt + ↑ / ↓`, enable multi-cursor mode to edit multiple lines simultaneously.
+- **Add Cursor to Line Ends**: After selecting multiple lines of text, add a cursor at the end of each line.
+
+
+
+
+ View: Interface Layout and Panel Control
+
+This menu is mainly responsible for: **Toggle Sidebar/Panel**, **Adjust Layout**, **Command Palette**, **Output and Debug Console**.
+
+- **Command Palette…**: `Ctrl + Shift + P` / `F1`, VS Code's central command center, can search and execute all commands.
+- **Open View…**: Quickly open specific sidebar views (such as Explorer, Source Control).
+- **Appearance**: Control fullscreen, menu bar visibility, sidebar position, zoom level (Zoom In/Out).
+- **Editor Layout**: Split editor (Split Up/Down/Left/Right) for side-by-side code comparison.
+- **Explorer / Search / Source Control / Run / Extensions**: Directly switch views in the Activity Bar.
+- **Problems / Output / Debug Console / Terminal**: Directly control the display content of the bottom panel.
+- **Word Wrap**: `Alt + Z`, control whether long lines of code automatically wrap (does not affect actual file content).
+
+
+
+
+ Go: Code Navigation and Jumping
+
+This menu is mainly responsible for: **Jumping Between Files**, **Jumping Between Symbols (Functions/Variables)**.
+
+- **Back / Forward**: Like a browser, jump between your cursor history positions.
+- **Switch Editor…**: Quickly switch between opened tabs.
+- **Go to File…**: `Ctrl + P`, type filename to quickly open files.
+- **Go to Symbol in Editor…**: `Ctrl + Shift + O`, list functions/classes/variables in the current file for quick jumping.
+- **Go to Definition**: `F12`, jump to the definition of the variable or function at the cursor.
+- **Go to References**: `Shift + F12`, see where this variable or function is used.
+- **Go to Line/Column…**: `Ctrl + G`, jump to a specified line number.
+
+
+
+
+ Run: Debugging and Execution
+
+This menu is mainly responsible for: **Start Debugging**, **Breakpoint Management**.
+
+- **Start Debugging**: `F5`, run the program in debug mode (supports breakpoints, variable watching).
+- **Run Without Debugging**: `Ctrl + F5`, run the program directly without attaching a debugger (slightly faster).
+- **Stop Debugging**: Forcefully end the current debugging session.
+- **Restart Debugging**: Run again.
+- **Toggle Breakpoint**: `F9`, add or remove a red dot (breakpoint) on the current line.
+- **New Breakpoint**: Supports conditional breakpoints, log breakpoints, and other advanced features.
+
+
+
+
+ Terminal: Integrated Command Line
+
+This menu is mainly responsible for: **New Terminal**, **Manage Terminal Windows**.
+
+- **New Terminal**: Open a new Shell (PowerShell/Bash/Zsh) in the bottom panel.
+- **Split Terminal**: Split left/right/up/down in the same terminal panel to run multiple commands simultaneously.
+- **Run Task…**: Run build/test tasks defined in `tasks.json`.
+
+
+
+
+ Help: Documentation and Feedback
+
+- **Welcome**: Open the welcome page (contains getting started guide, recent projects).
+- **Show All Commands**: Same as Command Palette.
+- **Documentation**: Jump to official documentation.
+- **Editor Playground**: Interactive tutorial for learning editing techniques.
+- **Check for Updates…**: Manually check for updates.
+- **About**: View version number, build time, Electron/Node version information.
+
+
diff --git a/docs/en/stage-0/index.md b/docs/en/stage-0/index.md
index ec13257..8c7bb88 100644
--- a/docs/en/stage-0/index.md
+++ b/docs/en/stage-0/index.md
@@ -66,17 +66,17 @@ Master the Vibe Coding workflow, learn to deconstruct requirements, and independ
@@ -93,17 +93,17 @@ Master the Vibe Coding workflow, learn to deconstruct requirements, and independ
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
index 07d67ba..fd68f78 100644
--- 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
@@ -359,3 +359,1011 @@ Through the interface below, you can successfully add a model (note: after selec
:::
+
+### 4.3 Step 2: Chat in the Sidebar and Have AI Design a Snake Game with React
+
+Next, open the AI chat sidebar: usually by pressing `Ctrl+L` or clicking the chat icon on the right. Then enter a clear prompt:
+
+> Please implement a Snake game using React architecture, including keyboard controls, growing and scoring when eating food, and displaying "Game Over" with restart support when hitting walls or itself. After implementation, help me start this project. If any program environment is not installed, automatically install the missing environment.
+
+During this process, you need to realize that AI is not just a chat model—it can help you operate your local environment: creating files, installing dependencies, executing startup commands, etc. You can directly describe your goals in natural language, and let AI decide which specific commands to execute and how to organize the code.
+
+If problems occur during execution, AI will display errors and solutions in the conversation. You can continue to have it adjust through dialogue without having to remember all command details yourself.
+
+::: warning ⚠️ Important Note
+As shown in the figure below, **sometimes the AI Agent will pause during execution because it needs to wait for you to input some information for interaction**, such as entering a created name, or pressing Enter to confirm command execution, or clicking a command to execute. Usually we just press Enter directly. If you're unsure what this step requires, you can take a screenshot of the current interface and ask the large model what operation should be performed.
+:::
+
+As shown, here we need to click Run to confirm:
+
+
+As shown, here we just need to input y to confirm:
+
+
+
+
+As shown, here we are creating a template but don't know how to operate. We can take a screenshot of this part and ask the large model:
+
+
+
+Another reason the AI Agent pauses during execution is because it has started a "service." Our Snake game itself is a type of "service." If you see a URL with the following command, it means the Agent has executed a local computer service for us. We can visit the corresponding URL to access our Snake game. Since the service needs to run continuously, it will pause here. We just need to click the `Skip` button.
+
+
+
+During this process, if you encounter some terms and content you don't understand, don't worry. You can refer to the "Computer Terminology Explanation" section in the appendix, or directly consult AI, or ask questions in time!
+
+If you encounter unexpected phenomena during the process, such as the snake not ending the game when hitting a wall, or the snake not moving after clicking start, you just need to describe the phenomenon to the sidebar Agent. If you encounter error problems, remember to take a screenshot or copy the error to the sidebar Agent. If it still can't be solved after multiple attempts, please try changing the model.
+
+After a short while, we can get results similar to z.ai:
+
+
+
+We can click the checkmark in the bottom right corner to confirm code changes, or click the `Cancel` button to cancel changes. Or click on the "2 files need review" area to expand and view the modified code.
+
+It's also worth noting that since code modifications may not always be correct, we need to know that all IDE Agents support code rollback. For example, if I accidentally made a wrong modification operation here, or if the result of this operation is unsatisfactory, after the modification is complete, we can return to the input box area and click the Revert button to roll back the operation to the state before modification. You can modify the input text for another operation:
+
+
+
+### 4.4 Step 3 (Optional): Ask AI About Code Implementation Details
+
+When the Snake game is running normally, if you're not yet familiar with frontend or React, you can continue in the same chat window and ask AI to guide you through the code in as colloquial a way as possible. You don't need to switch tools or deliberately look through documentation—just keep asking questions about the current project.
+
+A practical approach is to have AI first give an overall explanation of "how the game moves," then break it down into specific details. For example, you can directly ask:
+
+> "Please explain from top to bottom how this Snake game moves step by step? Try to use as few technical terms as possible."
+
+
+
+Then follow up on key points based on its answer, such as:
+
+> "What data structure is used to record each segment of the snake's body on the screen? Can you give an analogy?"
+> "How do you control 'moving once every while'? Which section of code is this in?"
+> "When the snake eats food, what steps do you take? Where is the logic that determines it ate something?"
+> "Where in the code are hitting walls and hitting itself judged respectively?"
+
+If you see a certain file (like `SnakeGame.tsx`) but have no idea what it's doing, you can also directly ask AI to explain it in sections:
+
+> "Please explain `SnakeGame.tsx` in several functional blocks: what is each block roughly responsible for, using simpler language."
+
+In this round of dialogue, you can treat any word you don't understand as an entry point for follow-up questions, such as:
+
+> "What exactly does 'state' mean in what you just said? Can you explain it with a real-life example?"
+> "What does 'timer' mainly do here? What would happen if it were removed?"
+
+Through this method, your goal is not to memorize all concepts at once, but to first understand three things: what core data exists in this game (snake, food, score, game state, etc.), when this data changes (moving, eating food, game over, etc.), and which small section of code corresponds to each change. Once these three points are clear, you can basically understand the main logic of this code.
+
+### 4.5 Step 4: Have AI Make the Interface Look Better
+
+First, a reminder for beginners: don't just tell AI "I want to make this interface look better." This statement is too vague even for human designers, let alone models—what style does "good-looking" mean, which parts need adjustment, is it a layout problem or a color problem? AI can't read all this from your one sentence. To make AI truly produce results close to what you have in mind, you need to learn to break down the vague goal of "I want it to look good" into a series of specific, executable small requirements.
+
+For example, many people initially say something like this:
+
+> "I want to make this interface look a bit better."
+
+Instead, you can first give a set of overall requirements:
+
+> "Please help me beautify the game interface overall:
+>
+> - Center the game area, don't stick it to the top-left corner;
+> - Change to a lighter background color to make the snake and food more prominent;
+> - Enlarge the score and place it in a prominent position;
+> - Use blue as the main color scheme to beautify the overall color scheme and buttons."
+
+If you want clearer feedback when the game ends, you can further supplement:
+
+> "When the game ends, please display 'Game Over' in the center of the screen, with a 'Restart' button below it that can reset the game."
+
+AI will directly modify React components and styles based on your description. After saving, refresh the browser to see the new interface. If the effect still differs from what you imagined, you can continue making small adjustments, such as:
+
+> "Make the score a bit larger and the color more prominent."
+> "Make the game area more compact with some margin around it."
+> "Change the restart button to a blue rounded style, centered below the prompt."
+
+At this stage, if a modification causes an error, you don't need to troubleshoot it yourself. Just copy the error message to the chat window, or provide a brief description like "This is the error that appeared after I beautified the interface," and let AI locate and fix it within the current project context. This way you can gradually polish a running demo into a small finished product with a clear interface and smooth interactions through the cycle of "continuous dialogue, continuous refreshing."
+
+### 4.6 (Optional) Reference z.ai Architecture to Modify Snake Results
+
+For vibe coding beginners, the hardest thing is not knowing what counts as "best practices" or what architecture is most suitable; because you don't know computer basics, you can't guide AI well. The solution to this problem is "direct reference." Remember when we said you can view code in z.ai? In fact, the corresponding README (the part used in projects to introduce functionality and technical architecture) already gives a best architecture reference:
+
+
+
+If we want the local result to match the z.ai result as closely as possible, we can copy all the content of this README and paste it into Trae's sidebar, asking it to modify the local code according to the README architecture.
+
+
+
+Finally, we can get page design styles highly similar to z.ai:
+
+
+
+
+
+
+
+
+
+## 5. What Each Button on the Interface Does
+
+In the above operations, we've quickly run through the minimum program generation loop, but we're still not familiar with the IDE. To thoroughly familiarize ourselves with this tool that we'll be working with long-term, we'll provide in-depth explanations of every detail of the IDE in this section. Starting with the interface, different AI IDEs have slightly different interfaces, but most follow the [VS Code layout](https://code.visualstudio.com/docs/getstarted/getting-started).
+
+
+
+The specific function of each part is:
+
+- **Title Bar**: Displays file name and window control buttons.
+- **Activity Bar**: Switches between functional views like files and search.
+- **Side Bar**: Displays specific content like file lists.
+- **Editor Groups**: The core area for writing code.
+- **Breadcrumbs**: Shows file path and supports navigation.
+- **Minimap**: Quick preview and positioning of code.
+- **Panel**: Contains terminal and output windows.
+- **Status Bar**: Displays current environment status.
+
+For more detailed explanations, please refer to the [Virtual IDE Visualization section in the Appendix](/zh-cn/appendix/2-development-tools/ide-basics).
+
+
+
+
+
+
+
+## 6. How to Talk to AI Effectively
+
+As AI capabilities become stronger and stronger, we can delegate much of the "programmer writes code" work to AI. However, in actual use, you'll find that using the same AI, some people can get a working small project in a few sentences, while others chat for a long time but get results completely different from what they wanted. The difference often lies not in "who is smarter," but in—whether the way you talk to AI is specific enough and step-by-step enough. This section introduces some questioning methods suitable for complete beginners from several common scenarios, helping you more stably get usable results from AI.
+
+### 6.1 Clarify Your Requirements: From "Vague Idea" to "Specific Description"
+
+Many people, when first using AI, are accustomed to saying only one very general sentence, such as:
+
+> "Help me make a webpage."
+> "Help me write a small program."
+
+In this case, AI can only "imagine" what you want, so it will casually give you something that looks quite complete, but often differs greatly from what you really want to do. To make AI understand you better, you need to break down the "idea in your head" and explain it step by step.
+
+You can supplement from these aspects:
+
+1. **Tell it what you're using this thing for**
+ For example, don't just say "personal website," but say:
+ - "I want to make a personal profile webpage with only one page of content, to send to recruiters."
+
+2. **Tell it roughly what blocks of content you need**
+ No need to use professional terms, just describe what you hope appears on the page, such as:
+ - "The page should have three sections: at the top is my name and a self-introduction sentence, the middle lists several work experiences, and the bottom puts email and WeChat ID."
+
+3. **Tell it your level and limitations**
+ Let AI do it in a way that beginners can accept, such as:
+ - "I can't write code at all, please use the simplest method so I can directly copy it into one file and open it in the browser."
+
+4. **Tell it how you hope to get the results**
+ For example:
+ - "Please give me complete code that can be directly saved as `index.html` and opened in the browser."
+
+Putting it together, you can say this to AI:
+
+> "I can't write code at all and want to make a personal profile webpage with only one page of content, to send to recruiters.
+> The page needs three sections: the top line is my name and a self-introduction sentence, the middle is several work experiences, and the bottom is email and WeChat ID.
+
+When you clarify this information, AI can get closer to your real needs, rather than casually giving you something "that looks impressive but is useless."
+
+### 6.2 Use the Right Rhythm: "Get It Running" First, Then Gradually Make It Complex
+
+For complete beginners, the most common pitfall is: wanting to make something "very complete" and "with many features" right from the start.
+For example:
+
+> "Help me make a website like Taobao."
+> "Help me make a system with registration, login, and ordering."
+
+The result is often: AI gives you a large chunk of code, which either won't open or has errors everywhere after you copy it; you also can't understand where the problem is, and finally have to give up.
+
+A better approach is to **actively control the rhythm**, letting AI follow you step by step, rather than throwing everything at you at once. You can request in this order:
+
+1. **First step: Ask for a "minimal example"**
+ Only check one thing: can you see something in the browser?
+ For example:
+
+ > "Please first give me the simplest example, as long as I can see a line saying 'This is my homepage' in the browser.
+ > Then tell me step by step: what should the file name be, how should I save it, and how to open it."
+
+2. **Second step: Slowly add complete content on this basis**
+ After you confirm "I can indeed see that line of text," then say:
+
+ > "On the basis of what we just had, help me add a 'Work Experience' area and send me the complete code again. Don't just send the changed parts."
+
+3. **Third step: After the structure is almost done, then consider whether it looks good**
+ For example:
+ > "Now the page can display content normally. Next, please help me beautify it a bit: center it overall, make the title larger, and use a more comfortable font. Please give me the updated complete code."
+
+With each addition, you run it once first to confirm there really is a change before letting AI continue. This way, even if something goes wrong at any step, you can quickly return to the "previous version that was working" state without having to start completely from scratch.
+
+### 6.3 Make Good Use of Screenshots and Copying: If You Can't Say It, "Throw the Screen at AI"
+
+Many difficulties complete beginners encounter don't lie in "not knowing how to modify code," but in **not knowing how to describe the problem**.
+For example:
+
+- A bunch of English errors suddenly pop up in the browser, which you completely don't understand.
+- The webpage layout is different from what you wanted, but you don't know what words to use to describe it.
+
+In these cases, you don't need to force out professional terms. The simplest way is to **throw what you see directly at AI**.
+
+You can do this:
+
+1. **Copy error text**
+ When you see a string of red error messages, you can directly copy them out and say:
+
+ > "This is the complete error message that appeared after I ran it. I don't understand this English, please first explain in words that ordinary people can understand what this roughly means.
+ > Then tell me what is the simplest way I should modify it now."
+
+2. **Show AI a screenshot**
+ If you feel "this page just looks wrong" but can't describe it, you can:
+ - Take a screenshot of the current page;
+ - Copy the entire section of code you're using to AI;
+ - Then explain:
+ > "This is what the page looks like now, this is my current complete code.
+ > I originally wanted it to be a three-column layout, but now it's become one column. Please help me find the reason and give me a corrected complete code."
+
+ ::: tip 💡 Supplementary Note on Screenshot Functionality
+
+ It's important to note that **not all AI models support "looking at pictures."** This involves two different concepts:
+
+ - **Pure text large models (LLM)**: Can only process text input and cannot recognize image content. If you send it a screenshot, it will either refuse to process it or cannot correctly understand the information in the image.
+
+ - **Multimodal models**: Can process multiple types of input such as text and images simultaneously, can "understand" the screenshots you send, and give suggestions based on the image content.
+
+ **Common model capability reference** (taking models available in Trae as an example):
+
+ | Model | Supports Image Input |
+ |------|-----------------|
+ | Doubao-Seed Series | ✅ Supported |
+ | GLM-4.7 / 4.6 | ❌ Not Supported |
+ | MiniMax-M2.1 / M2 | ❌ Not Supported |
+ | DeepSeek-V3.1 | ❌ Not Supported |
+ | Kimi-K2.5 | ✅ Supported |
+ | Kimi-K2-0905 | ❌ Not Supported |
+ | Qwen-3-Coder | ❌ Not Supported |
+ | Gemini Series | ✅ Supported |
+ | GPT Series | ✅ Supported |
+
+ **Usage suggestion**: If you want AI to help you troubleshoot interface problems through screenshots, please first confirm that the model you are using supports image input. If not supported, you can use text to describe the problem, or copy and paste error messages to AI.
+
+ :::
+
+3. **Encounter a webpage you like and want to make something similar**
+ No need to say "what is this layout called," just:
+ - Take a screenshot or copy the page's main title and paragraphs;
+ - Then say:
+ > "I want to make a page with a similar structure to this, doesn't need to be exactly the same.
+ > Please help me build a similar framework with simpler code, then I'll replace the text with my own."
+
+Simply put: you're responsible for "moving what you see to AI," then using the simplest words to say "I hope it becomes like this"; the rest of "translating into code, explaining terms, finding problems" is left to AI.
+
+### 6.4 When AI-Generated Code Doesn't Work: A Universal Response Method
+
+In actual practice, you will definitely encounter this situation:
+AI seriously gave you a piece of code, and you honestly copied it in, but the result is either a blank browser page or completely different from what it said.
+This doesn't mean you "can't learn," nor does it mean AI is completely wrong, but rather that you and AI are still missing a few rounds of "back-and-forth confirmation."
+
+When code "doesn't work," you can follow this fixed process to talk to AI:
+
+1. **First clearly state "what you did + what it looks like now"**
+ Avoid just saying "won't open" or "not working." You can describe it like this:
+
+ > After opening, the page is completely blank, not showing the welcome text you mentioned.
+ > I opened the xxxx page, and the part I just mentioned isn't there, this doesn't work.
+
+2. **Send AI your current complete code**
+ Many times the problem is: you copied one line less, or mixed content from the previous and current times together.
+ You can say:
+
+ > "Below is all the code currently in my file.
+ > Please compare to see if anything is missing, written wrong, or in the wrong order.
+ > Please directly give me a corrected complete code, don't just send a small section."
+
+3. **If there are error prompts, provide them together**
+ For example, errors that pop up in the top-right corner of the browser, or some red text at the bottom. You can:
+ - Copy out the error text;
+ - Or take a screenshot;
+ - Then say:
+ > "This is the error prompt I see. I completely don't understand it, please first explain in simple terms what this problem roughly is, then tell me which lines need to be modified most urgently now."
+
+4. **Ask the other party to use "beginner mode" to explain step by step**
+ You can directly state your situation and ask it not to skip intermediate steps:
+
+ > "I can't write code at all, please tell me step by step:
+ > Step 1: which line to modify,
+ > Step 2: how to save,
+ > Step 3: how to reopen or refresh the page.
+ > Please write out each step in complete sentences."
+
+5. **Finally, ask it to help you do a "what you should see" comparison**
+ For example:
+ > Please first say, according to your corrected code, what content should I normally see when I open the webpage.
+
+As long as you follow this process to interact with AI, most "code not working" situations can be resolved in a few rounds of back-and-forth.
+At the same time, you will gradually become familiar with common problem types, and next time you encounter similar situations, you can solve them directly.
+
+## 7. Summary and Next Steps
+
+In this chapter, you completed an upgrade from "playing an AI-generated Snake in a webpage" to "building a small game yourself with an AI IDE locally." You roughly figured out three things: why writing code can't be separated from an IDE like VS Code; on this basis, adding AI (Trae, Cursor, etc.) makes the IDE no longer just a toolbox, but adds an "intern engineer" who can understand natural language, help you create files, install environments, and modify code; and what each area of the IDE interface (left files, bottom terminal, middle editing area, right AI panel) is responsible for, so you're no longer confused when using it.
+
+More importantly, you've actually run through a complete process once: create an empty folder locally → open with AI IDE → describe requirements in sidebar dialogue → let AI generate project and start development server → when problems occur, throw "phenomenon + complete code + error screenshot" to AI together, asking it to fix step by step in "beginner mode." In this process, you also practiced how to write more effective prompts: clarify goals, content structure, and your level, control the rhythm well, from "get it running first" to "then make it look good, make it fun."
+
+In the next chapter, we'll shift focus from "knowing how to use tools" to "making a prototype that people actually want to use": starting from the user perspective, designing rules, interactions, and feedback, then letting AI help you turn these ideas into a product prototype.
+
+## 8. 📚 Assignment: Make a More Complex Game with Local AI IDE
+
+
+
+
🚀 Challenge Task: Build Your Own Game
+
+
+
+ You've already made a Snake game with a local AI IDE. Now please challenge yourself with a slightly more complex small game, walking through the complete process of "describe requirements → generate project → run locally → debug and iterate."
+
+
+
+
+ Choose a game more complex than Snake
+
+
Could be Tetris, Whack-a-Mole, Minesweeper, 2048, Aircraft Battle, etc.
+
Or a simple original game you imagine yourself
+
+
+
+ Must use local AI IDE to complete the entire process
+
+
Create a new empty folder and open it with AI IDE
+
Describe your game requirements clearly in the sidebar chat
+
Let AI be responsible for creating files, building project structure, and implementing main logic
+
Start the development server locally to ensure the game can run normally
+
+
+
+ Have basic "playability" and feedback
+
+
At least include three states: start, in-progress, and end
+
Players have clear operation methods (keyboard or mouse)
+
Clear score or progress feedback on the screen
+
+
+
+ At least 2+ rounds of iteration
+
+
First round: let AI make a "playable" version
+
Second round and beyond: gradually propose specific improvements (style, difficulty, interaction optimization, etc.)
+
+
+
+
+
+# Appendix
+
+
+
Appendix Navigation
+
+ Here are "look up when needed" supplementary materials: come back when you encounter terms you don't understand or can't find interface entries.
+
+
+
+ 🖥️ Tool Interface
+ IDE / Terminal / Panel
+
+
+ 🌐 Network Services
+ URL / Port / Local
+
+
+ ⚙️ Frontend & Backend
+ API / JSON / Interface
+
+
+ 📝 Code Basics
+ Variable / Function / Component
+
+
+
+
+ 🐞 Debugging
+ Bug / Breakpoint / Log
+
+
+ 📂 Project Management
+ Git / Repository / Commit
+
+
+ 🤖 AI Tools
+ Agent / Model / Key
+
+
+ 🛠️ Browser
+ DevTools / Console
+
+
+
+
+You don't need to deliberately memorize this section. What's more important is to first establish an impression in your mind.
+
+## [1. Words Related to "Tool Interface"](#appendix-1-map)
+
+### 1. IDE, Editor, Terminal
+
+**IDE (Integrated Development Environment)**
+You can think of an IDE as a "programmer's workbench":
+
+- One side is a writing desk (editor),
+- One side has power outlets and buttons (run, debug),
+- Drawers contain various small tools (search, version management).
+ VS Code, Trae, Cursor all belong to IDEs or tools based on IDEs.
+
+**Code Editor (Editor)**
+More like an "advanced notepad," only responsible for:
+
+- Letting you type code;
+- Using colors to distinguish different content (syntax highlighting);
+- Giving you auto-completion.
+ The area in the IDE where you write code is the code editor.
+
+**Terminal / Command Line (Terminal / Command Line Window)**
+A window with black background and white text, where you **input commands** for the computer to work:
+
+- For example: `npm run dev` means "help me start the development server";
+- `python main.py` means "run this Python file."
+ You can think of it as: "You send the computer text message commands one by one, and it replies with execution results in text."
+
+### 2. Several Common Areas in the IDE
+
+**Activity Bar**
+The row of small vertical icons on the far left, like "function tabs":
+
+- Click file icon → file list displays on the left;
+- Click magnifying glass icon → left becomes search;
+- Click Git icon → left displays version management.
+
+**Side Bar**
+The large area to the right of the Activity Bar, specifically displaying content for the current mode:
+
+- File mode: shows files and folders in the project;
+- Search mode: shows search results list;
+- Source control mode: shows which files have been modified.
+
+**Editor Area**
+The largest area in the middle, where you actually see and modify content after opening a file;
+The tabs above are "which files are currently open."
+
+**Panel**
+Generally at the bottom, common types include:
+
+- Terminal: input commands to run projects;
+- Problems: lists error files and line numbers;
+- Output: some tool-printed runtime information;
+- Debug Console: output during debugging.
+
+**Status Bar**
+The thin bar at the very bottom:
+
+- Displays what language the current file is (JS, HTML, Python, etc.);
+- Displays whether indentation is "2 spaces" or "4 spaces";
+- Displays whether there are errors, what the current Git branch is.
+ You can think of it as "a small health check of the current editing environment."
+
+## [2. Words Related to "Webpage / Network / Service"](#appendix-1-map)
+
+### 1. URL, HTTP, Port, Local Service
+
+**URL (Web Address)**
+That string of things in the browser address bar, such as:
+
+- `https://www.trae.cn/`
+- `http://localhost:3000/`
+ It's like "the complete address of a room in the internet world."
+
+**HTTP / HTTPS**
+The `http://` or `https://` you see at the beginning of a URL:
+
+- HTTP: ordinary transmission method;
+- HTTPS: adds a layer of encryption, more secure.
+ You can first remember: "When writing webpage addresses, usually start with `http` or `https`."
+
+**Port (Port)**
+You can imagine a computer as a building, and ports are **room numbers for each room**:
+
+- `:3000` means room 3000;
+- The same computer can run multiple services simultaneously, each occupying a port.
+ `http://localhost:3000` means "access the service running in room 3000 on my own computer."
+
+**Local (Local / localhost)**
+Refers to your own computer.
+
+- `localhost` can be understood as "this machine itself."
+ When you access `http://localhost:3000`, you're actually interacting with a program running on your own computer, not accessing someone else's server online.
+
+**Service (Service / Server)**
+A "service" is a **program that keeps running in the background, always listening for your commands**:
+
+- Web service: when a browser accesses an address, it returns webpage content;
+- Game service: responsible for managing matches, saves, leaderboards, etc.
+ Executing `npm run dev` in the terminal to start a project is essentially "opening a web service locally."
+
+## [3. Words Related to "Frontend / Backend / Data"](#appendix-1-map)
+
+### 1. Frontend, Backend
+
+**Frontend**
+The part that users **can see and click**:
+
+- Buttons, text, images, animations on webpages;
+- Pages written in React / Vue.
+ Responsible for displaying interfaces and responding to user operations (clicks, inputs, drags, etc.).
+
+**Backend**
+The part that users **cannot see**, running on the server:
+
+- Storing and reading data (user information, orders, scores, etc.);
+- Executing business rules (login verification, permission judgment).
+ You can think of frontend as "storefront and clerk," and backend as "warehouse and ledger system."
+
+### 2. Interface, Request, Response, JSON
+
+**Interface / API**
+A set of "question + answer" rules agreed upon in advance between frontend and backend.
+
+- Frontend says: "I'll ask you using this address, this format";
+- Backend says: "I'll return results to you in this format."
+
+**Request (Request)**
+A "question" sent from frontend to backend:
+
+- Where is the request going (URL);
+- What method is used (GET, POST, etc.);
+- What parameters are brought (such as user ID).
+
+**Response (Response)**
+The "answer" given by backend to frontend:
+
+- Status code (200 success, 404 not found, 500 server error);
+- Actual data (mostly JSON).
+
+**JSON**
+A format for representing data using **syntax very similar to JavaScript code**, such as:
+
+```json
+{
+ "name": "Alice",
+ "score": 120
+}
+```
+
+Can be understood as "a machine version of key-value notepad," often used by frontend and backend to exchange data.
+
+## [4. Words Related to "Writing Code Itself"](#appendix-1-map)
+
+### 1. Variable, Identifier, State
+
+**Variable (Variable)**
+"A label attached to a piece of data."
+
+- For example, recording the score as `score`;
+- Later using the name `score`, you can read and write this data:
+
+```js
+let score = 0
+score = score + 10
+```
+
+**Identifier (Identifier)**
+A general term for "various names you give yourself":
+
+- Variable name: `score`
+- Function name: `moveSnake`
+- Component name: `SnakeGame`
+ Like naming folders "Photos," "Work," "Bills" for easy distinction between different "things" in code.
+
+**State (State)**
+The "key situation record" of the program's current state:
+
+- Whether the game has ended;
+- Which grid the snake is currently on;
+- What the current score is.
+ In React, it's generally understood this way: **when state changes, the interface must follow and update**.
+
+### 2. Function, Component, Module
+
+**Function (Function)**
+Package something that "can be done repeatedly" and give it a name:
+
+```js
+function sayHello(name) {
+ console.log('Hello, ' + name)
+}
+```
+
+Later, just writing `sayHello('Bob')` equals executing those lines again.
+
+**Component (Component)**
+In frontend, "a small interface + small logic that can be reused":
+
+- A button can be a component;
+- A top navigation can be a component;
+- The entire game area can also be a component.
+ Components can be assembled together, like building with LEGO.
+
+**Module (Module)**
+"A file composed of a group of related codes":
+
+- `snakeLogic.ts` specifically stores code related to "how the snake moves";
+- `score.ts` specifically stores code for calculating scores.
+ Modules can "import / export" between each other, like tools in different drawers.
+
+### 3. Syntax, Programming Language, Framework
+
+**Syntax (Syntax)**
+The "grammar rules" and "punctuation habits" of a programming language:
+
+- Strings need quotes;
+- Whether to write a semicolon at the end of each statement;
+- Code blocks need to be wrapped in `{}`.
+ Writing syntax errors, compilers / interpreters will directly report "syntax errors."
+
+**Programming Language (Programming Language)**
+A complete set of rules and vocabulary for communicating with computers, such as:
+
+- JavaScript, Python, Java, C++, Go...
+ Different languages are suitable for different things, have different writing styles and tool ecosystems.
+
+**Framework (Framework)**
+A large set of code and patterns that others have "pre-built the skeleton" for you:
+
+- Frontend: React, Vue (helping you handle interface updates, state management, etc.);
+- Backend: Django, Spring Boot, etc.
+ You're essentially "filling in content on a ready-made skeleton," much easier than building from scratch.
+
+## [5. Words Related to "Debugging / Troubleshooting"](#appendix-1-map)
+
+### 1. Bug, Error, Log / console.log
+
+**Bug**
+When program behavior differs from what you expect, that's a bug:
+
+- Buttons that should appear don't appear;
+- Should add 10 points but added a bunch more;
+- Page shows white screen as soon as it opens.
+
+**Error Message (Error Message)**
+That "scary-looking" English that appears on the screen / in the terminal after a program crashes.
+Although ugly, it usually tells you:
+
+- Roughly where the error is;
+- Which file, near which line needs checking.
+ You can directly copy it and throw it to AI for translation and analysis.
+
+**Log (Log)**
+What the program "says" during operation.
+Most common in frontend is:
+
+```js
+console.log('Current score', score)
+```
+
+You can think of it as: **actively reporting numbers at key steps to confirm whether the program is running as you expect**.
+
+> **What is console.log?**
+>
+> - `console` can be understood as "a small blackboard for debugging";
+> - `.log` is "writing a line on the small blackboard";
+> - Press F12 in the browser to open the Console panel in developer tools to see these outputs.
+
+### 2. Debug, Breakpoint, Step-by-Step Execution, Snapshot
+
+**Debug (Debug / Debugging)**
+When a program has problems, instead of randomly modifying:
+
+- Let the program pause at a certain line (breakpoint);
+- Look at the value of each variable at the moment;
+- Walk through step by step, observing "where it starts to go wrong."
+
+**Breakpoint (Breakpoint)**
+You can think of a breakpoint as "a pause button inserted at this line":
+
+- Programs normally run all the way through;
+- When running to the line where you inserted the breakpoint, it will temporarily stop and wait for your inspection.
+
+**Step-by-Step Execution (Step)**
+After stopping from a breakpoint, you can choose:
+
+- Execute line by line (step over);
+- Go inside a certain function to see details (step into).
+ Like watching a dance broken down into moves, rather than watching a fast-forward video directly.
+
+**Snapshot (Snapshot) — Simplified Understanding**
+Here "snapshot" can be understood as:
+
+> **Taking a photo of the "current state" at a certain point in time for future comparison.**
+> In actual tools, "snapshot" may refer to:
+
+- The complete state of the project at the moment of a commit;
+- The overall situation of memory / variables at a certain point during debugging.
+ Just remember this analogy for now: **snapshot ≈ a photo of state at a certain moment**.
+
+## [6. Words Related to "Project Management"](#appendix-1-map)
+
+### 1. Project, Workspace, Folder
+
+**Project (Project)**
+For implementing an application, placed in the same folder:
+
+- Source code files
+- Configuration files
+- Assets (images, audio, etc.)
+
+**Workspace (Workspace)**
+A concept used by VS Code / Trae to describe "what group of things is currently open this time":
+
+- Opening a folder → a simple workspace;
+- Sometimes multiple folders are combined into a multi-project workspace.
+
+### 2. Git, Repository, Commit
+
+**Git (Version Control Tool)**
+Can be understood as a "time machine" for projects:
+
+- After each batch of modifications, you can "take a version photo";
+- When needed in the future, you can return to a certain historical state.
+
+**Repository (Repository / Repo)**
+After enabling Git, that project folder with "version records" is called a "repository."
+
+**Commit (Commit)**
+Every time you feel "this wave of modifications counts as a阶段性成果," you can:
+
+- Write a description (such as: `Add score panel`);
+- Package all current modifications into a version;
+- Git will save the state at this moment.
+ This action is called "making a commit."
+
+## [7. Words Related to "AI Development Tools"](#appendix-1-map)
+
+### 1. AI IDE, Agent, SOLO Mode
+
+**AI IDE**
+On the basis of ordinary IDEs, adds a layer of AI that "can understand human language and take action itself":
+
+- You say "make a Snake game," it can help you set up the project, write code;
+- You give it a screenshot of an error, it can first explain then try to fix;
+- It can modify across multiple files together, not just complete line by line.
+
+**Agent (Agent)**
+You can think of an Agent as an **AI junior engineer on long-term standby**:
+
+- Will read your project structure;
+- Will break down tasks (install dependencies first, then generate code, then run project);
+- After errors occur, will adjust plans based on error information.
+
+**SOLO Mode (taking Trae as an example)**
+Means:
+
+> You only need to clearly state the "destination,"
+> It plans the "route" itself,
+> Executes step by step locally,
+> Only asks whether to continue at key nodes midway.
+
+### 2. Model, Key (API Key)
+
+**Model (Model, here specifically referring to large language models)**
+This word can be simply understood as "that big AI brain behind it":
+
+- Such as GPT, Claude, Kimi, GLM, etc.;
+- Different models have different levels in "understanding Chinese," "writing code," "reasoning";
+- AI IDEs usually allow switching between different models in dropdown menus.
+
+**Key / API Key**
+You can understand an API Key as **a very long "advanced password + ID number,"**
+Its only function is:
+
+> Tell someone else's server: "I'm which user, please allow me to use your AI service, and help me keep accounts."
+
+Key points:
+
+- This thing is usually a long string of random letters and numbers;
+- Can't be sent to public places (repositories, screenshots, group chats), others can impersonate your account if they get it;
+- Filling in the API Key in the tool is like "inserting the key into the lock," after which the tool can help you call the corresponding AI service.
+
+## [8. Words Related to "Browser / Developer Tools"](#appendix-1-map)
+
+**Chrome (Google Browser)**
+One of the most commonly used browsers for frontend development now:
+
+- Opens webpages fast;
+- Comes with relatively strong "developer tools" for easy problem checking.
+
+**Refresh (Refresh / Reload)**
+Reload the current webpage:
+
+- After modifying frontend code, if there are no automatic refresh tools, you need to manually refresh to see the effect.
+
+**Developer Tools (DevTools)**
+A set of tool panels in the browser specifically for developers:
+
+- View webpage structure (Elements);
+- View styles (Styles);
+- Check errors and logs (Console);
+- Check network requests (Network).
+ In Chrome, usually opened by pressing `F12` or `Ctrl+Shift+I`.
+
+**Console (Console)**
+A tab in developer tools, specifically displaying:
+
+- The output of your `console.log(...)`;
+- Errors that occurred during operation (red text).
+ You can think of it as "the program's chat box":
+- When the program has something to say, it writes here;
+- This is what you most often look at when debugging.
+
+If you encounter new words in the learning process later, you can also have AI assist you in supplementing all content in this style:
+
+- First write a sentence about "what it does";
+- Then write a sentence about "what you can imagine it as";
+- Finally give a particularly simple small example.
+ This way your "personal glossary" will grow longer and more practical, gradually enabling better communication with computers.
+
+---
+
+# Appendix 2: Visual Studio Code Menu Bar Analysis
+
+To help everyone understand the meaning of each option, here we provide an in-depth analysis of the menu bar:
+
+
+
+
+
+
+ File: Project and File Open/Save/Workspace Management
+
+This menu is mainly responsible for: **Creating/Opening Files**, **Opening Project Folders**, **Managing Workspaces**, **Saving and Closing**.
+
+> The most commonly used are: Open Folder to open a project; Open… to open a single file; then use Save / Save All to save changes, and finally use Close Editor / Close Folder to end the current work. Workspace-related content can be slowly learned as you get more projects, no need to understand everything at once.
+
+- **New Text File**: Create a new unnamed text buffer for temporary notes or quick pasting.
+- **New File…**: Create a new file in the project (usually asks you to choose path/name).
+- **New Window**: Open a new VS Code window instance.
+- **New Window with Profile**: Open a new window with a specified Profile (extension/settings combination), suitable for isolating environments for different courses/projects.
+- **Open…**: Open a single file for editing.
+- **Open Folder…**: Open a folder as the project root directory (the most commonly used "open project" method).
+- **Open Workspace from File…**: Open a `.code-workspace` file to load a workspace with multiple folders/specific settings.
+- **Open Recent**: Quickly access recently opened files/folders/workspaces.
+- **Add Folder to Workspace…**: Add another folder to the current workspace (forming a multi-root workspace).
+- **Save Workspace As…**: Save the current workspace structure as a `.code-workspace` file for easy sharing/reuse.
+- **Duplicate Workspace**: Duplicate the current workspace configuration (commonly used to create similar project environments).
+- **Save**: Save changes to the current file.
+- **Save As…**: Save the current file with a new name/path.
+- **Save All**: Save all opened files that have modifications.
+- **Share**: Entry related to sharing/collaboration (specific content depends on version and extensions).
+- **Auto Save**: Toggle auto-save strategy (e.g., delayed save/focus change save).
+- **Revert File**: Discard unsaved changes to the current file and revert to the disk version.
+- **Close Editor**: Close the current tab.
+- **Close Folder**: Close the current project folder (workspace becomes empty).
+- **Close Window**: Close the current VS Code window.
+
+
+
+
+ Edit: Basic Editing, Find/Replace, Comments and Quick Edit Actions
+
+This menu is mainly responsible for: **Undo/Redo**, **Cut/Copy/Paste**, **Find/Replace**, **Comments and Editor Actions** (improving editing efficiency).
+
+- **Undo / Redo**: The most basic operations for when you write code wrong.
+- **Cut / Copy / Paste**: Text transportation.
+- **Find / Replace**: Search or batch modify in the current file.
+- **Find in Files / Replace in Files**: Global (whole project) search and replace, very powerful but use with caution.
+- **Toggle Line Comment**: `Ctrl + /`, quickly comment/uncomment the current line.
+- **Toggle Block Comment**: `Shift + Alt + A`, quickly comment/uncomment the selected area.
+- **Emmet: Expand Abbreviation**: A powerful tool for HTML/CSS development, type shorthand and press Tab to expand code.
+
+
+
+
+ Selection: Multi-cursor and Smart Selection
+
+This menu is mainly responsible for: **Cursor Control**, **Multi-line Editing**, **Expand/Shrink Selection**. This is VS Code's killer feature for improving efficiency.
+
+- **Select All**: Select all content in the current file.
+- **Expand Selection / Shrink Selection**: Intelligently perceive syntax structure, gradually expand or shrink the selection range (e.g., word -> string -> inside parentheses -> whole line -> function body).
+- **Copy Line Up / Down**: Quickly clone the current line.
+- **Move Line Up / Down**: `Alt + ↑ / ↓`, adjust code line order directly without cut and paste.
+- **Add Cursor Above / Below**: `Ctrl + Alt + ↑ / ↓`, enable multi-cursor mode to edit multiple lines simultaneously.
+- **Add Cursor to Line Ends**: After selecting multiple lines of text, add a cursor at the end of each line.
+
+
+
+
+ View: Interface Layout and Panel Control
+
+This menu is mainly responsible for: **Toggle Sidebar/Panel**, **Adjust Layout**, **Command Palette**, **Output and Debug Console**.
+
+- **Command Palette…**: `Ctrl + Shift + P` / `F1`, VS Code's central command center, can search and execute all commands.
+- **Open View…**: Quickly open specific sidebar views (such as Explorer, Source Control).
+- **Appearance**: Control fullscreen, menu bar visibility, sidebar position, zoom level (Zoom In/Out).
+- **Editor Layout**: Split editor (Split Up/Down/Left/Right) for side-by-side code comparison.
+- **Explorer / Search / Source Control / Run / Extensions**: Directly switch views in the Activity Bar.
+- **Problems / Output / Debug Console / Terminal**: Directly control the display content of the bottom panel.
+- **Word Wrap**: `Alt + Z`, control whether long lines of code automatically wrap (does not affect actual file content).
+
+
+
+
+ Go: Code Navigation and Jumping
+
+This menu is mainly responsible for: **Jumping Between Files**, **Jumping Between Symbols (Functions/Variables)**.
+
+- **Back / Forward**: Like a browser, jump between your cursor history positions.
+- **Switch Editor…**: Quickly switch between opened tabs.
+- **Go to File…**: `Ctrl + P`, type filename to quickly open files.
+- **Go to Symbol in Editor…**: `Ctrl + Shift + O`, list functions/classes/variables in the current file for quick jumping.
+- **Go to Definition**: `F12`, jump to the definition of the variable or function at the cursor.
+- **Go to References**: `Shift + F12`, see where this variable or function is used.
+- **Go to Line/Column…**: `Ctrl + G`, jump to a specified line number.
+
+
+
+
+ Run: Debugging and Execution
+
+This menu is mainly responsible for: **Start Debugging**, **Breakpoint Management**.
+
+- **Start Debugging**: `F5`, run the program in debug mode (supports breakpoints, variable watching).
+- **Run Without Debugging**: `Ctrl + F5`, run the program directly without attaching a debugger (slightly faster).
+- **Stop Debugging**: Forcefully end the current debugging session.
+- **Restart Debugging**: Run again.
+- **Toggle Breakpoint**: `F9`, add or remove a red dot (breakpoint) on the current line.
+- **New Breakpoint**: Supports conditional breakpoints, log breakpoints, and other advanced features.
+
+
+
+
+ Terminal: Integrated Command Line
+
+This menu is mainly responsible for: **New Terminal**, **Manage Terminal Windows**.
+
+- **New Terminal**: Open a new Shell (PowerShell/Bash/Zsh) in the bottom panel.
+- **Split Terminal**: Split left/right/up/down in the same terminal panel to run multiple commands simultaneously.
+- **Run Task…**: Run build/test tasks defined in `tasks.json`.
+
+
+
+
+ Help: Documentation and Feedback
+
+- **Welcome**: Open the welcome page (contains getting started guide, recent projects).
+- **Show All Commands**: Same as Command Palette.
+- **Documentation**: Jump to official documentation.
+- **Editor Playground**: Interactive tutorial for learning editing techniques.
+- **Check for Updates…**: Manually check for updates.
+- **About**: View version number, build time, Electron/Node version information.
+
+
diff --git a/docs/zh-cn/appendix/5-data/data-analysis.md b/docs/zh-cn/appendix/5-data/data-analysis.md
index b6714c5..c8acd3a 100644
--- a/docs/zh-cn/appendix/5-data/data-analysis.md
+++ b/docs/zh-cn/appendix/5-data/data-analysis.md
@@ -1,118 +1,117 @@
-# 数据分析：拨开数字的迷雾
+# 数据分析：核心概念、逻辑与深度洞察
::: tip 🎯 核心问题
-**如果把网站比作人，数据到底是在检查什么？**
-当我们面对每天产生的惊人数据：几十亿行的日志、数以千万计的点击量，我们该怎么下手？是依靠 DAU (日活) 自满，还是对次日惊人下跌的留存率战战兢兢？本章以侦探探案的视角告诉你，怎样让这些死气沉沉的数字，自己开口说话。
+**如何从散乱的数据中提取出能够指导业务的“确定性”？**
+在互联网产品中，每秒都在产生海量的用户行为记录。仅看总量（如总访问量）往往会掩盖真相。本章将由浅入深，从基础统计学指标到高级业务分析模型，带你掌握数据分析的底层逻辑。
:::
---
-## 0. 全景图：从数字垃圾到金矿洞察
+## 0. 概述：数据分析的本质
-数据本身毫无生命。它们不过是安静地躺在磁盘扇区里，堆砌着毫无温度的 0 和 1。每一天有 100 万人在你的 APP 里注册，但其中可能有 80% 的人在头三分钟内就再也不回来了。
+> 很多人认为看一眼报表就是数据分析。如果你不理解“数据、信息、洞察”之间的转化逻辑，你就会被困在数字的海量细节中。学习本节是为了让你建立全局观，明白数据分析的最终目的不是为了“汇报”，而是为了“决策”。
-这些就是赤裸裸的“数据”。
-而我们该如何像一名法医或是名侦探一样，从一滩纷乱如麻的现场脚印中，剥茧抽丝，揪出潜藏背后的罪魁祸首呢？“发现问题、分析本质、指引改进”，这套流程的学名叫 **数据分析 (Data Analysis)**。
+数据分析并非简单的“报表汇总”，而是一个**信息降维**与**特征提取**的过程。
-如果把企业的运营比喻成一个人去医院做了体检：
-1. **收集体检单**：把肝功能、心电图全查出来（数据收集与埋点）。
-2. **血常规初诊**：看看身体各个指标的大概均值是否异常（描述性统计）。
-3. **CT扫出病原**：深入病灶查看到底大面上哪里出问题了（群体过滤与数据聚合）。
-4. **追溯病情**：观察健康下降的全过程，看看这病到底是哪一天落下的（留存和漏斗排查）。
+- **原始数据 (Raw Data)**：是零散、无序的记录（如：用户A在10:01点击了按钮B）。
+- **信息 (Information)**：是加工后的数据（如：今天有30%的用户点击了按钮B）。
+- **洞察 (Insight)**：是发现数据背后的规律（如：按钮B的点击率在移动端远高于PC端，说明移动端用户更依赖该功能）。
+
+我们的目标是建立一套系统的分析框架，通过“观测 -> 拆解 -> 定位 -> 决策”的闭环来驱动业务增长。
---
-## 1. 描述性统计：体温计与血常规
+## 1. 描述性统计：如何一句话概括全貌
-“最近我们班的成绩怎么这么差？”
-面对这样的疑问，如果你一条条念名字：“张三 52，李四 95...”，那简直是要发疯的事情。
+> 当面对 10 万行数据时，你不可能逐行查阅。你需要一种“信息压缩”的能力，用极少数的指标精准抓住数据的脉络。如果你不懂均值与中位数的统计陷阱，你就会在分析业务表现（如用户人均消费）时被极端数值误导，得出荒谬的结论。
-面对庞杂无垠的海量细节，我们发明了一种极为凝练的力量：用几个极致抽象的**指标**，来一把掐住整体数据的脉络。
+当数据集有数万条记录时，我们需要用极少数的“代表性指标”来描述其整体面貌。
-
+
-### 1.1 均值 (Mean)
-
-它就如同温度计，一把揽住了班级里的所有成员并简单平摊。但这把标尺有时候会撒谎。如果你正在和比尔盖茨一起吃饭，那你们这桌就拥有两个亿万富翁，但这并不能说明你同样身怀巨款。这就是均值在面对**极端值 (Outliers)** 时的脆弱。
+### 1.1 均值 (Mean)：整体水平的基准
+均值（算术平均数）是最直观的指标。
+- **计算逻辑**：所有数值的总和除以数据总量。
+- **局限性**：它极易受到**极端离群值 (Outliers)** 的干扰。
+- **示例**：如果 9 名员工月薪 5k，老板月薪 100k，则平均工资高达 1.45w。此时均值并不能真实代表大多数员工的收入水平。
### 1.2 中位数 (Median) 与 众数 (Mode)
+- **中位数**：将数据由小到大排序，取最中间位置的数值。它能有效抵御离群值的干扰，真实反映典型的“中间层”水平。
+- **众数**：数据集中出现频次最高的数值。在分析“用户最喜欢的商品”、“最常发生的错误代码”时，众数能最直接地指明群体倾向。
-此时我们引入了“把大家按名次站成一排”的理念，精确掐住站在正中央（第 50 分位数）的那个人的水平。不管比尔盖茨身价多高，只要他排在队尾，他就完全拉扯不了位于中央的那位普通人。
-而众数则是告诉你货架上卖的最火的那件爆款是什么（因为它是出现次数最多的常客）。
-
-### 1.3 标准差 (Standard Deviation)
-
-如果你和隔壁班的均值都是 80 分。隔壁班所有人考的都是 80 左右，而我们班是一半人满分 100，一半人刚刚及格 60。这怎么区分？
-方差和标准差就是一把尺，专门衡量这种“数据像散沙一样分散”或者“像砖块一样抱团”的聚合程度。
+### 1.3 标准差 (Standard Deviation)：分布的“宽窄”
+它描述了数据点距离均值的波动力度。
+- **低标准差**：数据非常集中，均值的代表性强（如：工厂流水线的零件尺寸）。
+- **高标准差**：数据分布散乱，个体差异极大。
+- **意义**：在性能监控中，高标准差往往意味着系统的稳定性不足，存在大量响应极慢的“长尾请求”。
---
-## 2. 数据聚合：上帝视角鸟瞰众生
+## 2. 数据聚合：挖掘群体的微观规律
-当我们凝视个人时，就像管中窥豹。一个人偶尔退货并不能说明这身衣服的质量有问题。但如果我们打开上帝视角，把零散的一件件碎片拼在一起呢？
+> “所有用户平均转化率 5%” 往往是一句毫无意义的真话。你必须学会如何把数据“切开”，才能发现不同地域、不同渠道、不同设备用户之间的巨大差异。聚合分析能带你穿透“大锅饭”般的平均值，直达那些被掩盖的真实业务痛点。
-这就来到了 **数据聚合 (Aggregation)** 的领域。
-我们经常会把海量订单，按着地区、年龄、或者是购买时间，像推倒多米诺骨牌一样给拢成一打一打的。
+个体行为往往具有偶然性，但群体行为具有统计规律。**数据聚合 (Aggregation)** 的核心在于通过特定的维度对人群进行“切片”。
-
+
-### 2.1 常见的上帝之手
+### 2.1 聚合的核心逻辑：拆分-计算-组合
+1. **拆分 (Split)**：根据某个属性（如：城市、注册渠道、新老用户）进行分组。
+2. **计算 (Apply)**：在每个组内执行聚合函数，如 `COUNT()` 计数、`SUM()` 求和、`AVG()` 求均值。
+3. **组合 (Combine)**：对比不同组的结果，发现差异点。
-比如我们常用 SQL（结构化查询语言）的：
-- **COUNT ()**：迅速数出这堆究竟有多少人。
-- **SUM ()**：把他们兜里的钱全部卷在一起加总。
-- **GROUP BY**：按照某种鲜明的属性（比如城市、或者是新老用户），把他们硬生生拆开分别摆好，这就叫做分组比对。
-
-这是一种摧枯拉朽的化繁为简：通过聚合，几百 G 巨大的行为轨迹表格被瞬间碾压成了短短的两三行汇总。
+### 2.2 为什么必须进行分组 (Group By)？
+汇总数据往往会掩盖问题。例如，整体转化率在涨，但拆分后发现其实是“上海地区”暴增拉高了整体，而其他地区都在跌。通过聚合分析，我们可以从“大锅饭”中精准定位到表现最优秀或最糟糕的分支。
---
-## 3. 漏斗模型：捕捉消失的幸存者
+## 3. 漏斗模型：定位价值链的“出血点”
-当你满心欢喜地投入千万广告费，拉来了 10 万名兴冲冲想要下单的用户。但第二天打开报表却如同坠入冰窟：实际付款到账的只有区区 1,200 人！
+> 你投入了大量资源拉来用户，结果成交寥寥，钱都白花了吗？漏斗模型能告诉你用户到底在哪个门槛被绊倒了。学会这一节，你能把“业务优化”从盲目猜测变成精准研发，将资源投入到转化率产出最高的环节。
-这几万人都死在这条路上的哪里了？
-这个时候，我们需要一把异常锋利的手术刀——**转化漏斗 (Funnel)**。
+用户从进入到完成最终目标（如付费）是一个层层筛选的过程。漏斗模型（Funnel）不仅是看最终转化率，更是为了看**在哪里丢了人**。
-
+
-### 3.1 横切业务链的断层
+### 3.1 核心转化指标
+- **总体转化率**：完成终点的总人数 / 进入起点的总人数。
+- **步骤转化率**：当前步骤人数 / 上一步骤人数（反映了该步的通过效率）。
+- **流失率**：1 - 步骤转化率。
-用户从进入店铺大门到最终结账，中间会经历一系列的惊险跨栏：
-
-- **第一关**：看到商品详情页（10万人）。
-- **第二关**：愿意拉到底点击购买（跌至6万人）。
-- **第三关**：填写那让人烦躁的收货地址（跌至3万人）。
-- **第四关**：打开支付系统输入复杂的验证码验证（终于只剩下最后生还的 1,200 人）。
-
-通过这张鲜血淋漓的“阵亡率清单”，你一眼就能看出：绝大多数人倒在了填写地址和支付跳转的过程上！比起盲目地去修改什么按钮颜色，**直接砍掉两项非必要的地址表单，才是救这帮快要在路上死绝的用户的致命灵丹**。
+### 3.2 深度分析思路
+如果某一环节的流失率异常偏高，说明在该处存在**体验摩擦**。例如：
+- 在注册页流失严重：说明表单太复杂或验证码收不到。
+- 在选择支付方式处流失：说明支付方式太少或跳转加载过慢。
+在漏斗最窄的地方投入力量进行优化，其收益通常是最大的。
---
-## 4. 留存分析：忠诚度的生死考验
+## 4. 留存分析：产品的“硬核”体检
-如果一款产品天天能像抽水机一样抽来大量用户，但池子底部却被挖开了一个大黑洞，漏水漏得精光。这能算是成功的商业模式吗？
+> 留存是产品价值的第一金标准。如果拉新是给桶加水，留存就是看这桶漏不漏。如果你只会看总访问量（流量）而不会分析留存（留客），你就无法判断产品是在健康成长，还是在玩一场注定崩盘的数字游戏。
-在这个领域，日活跃用户数（DAU）往往是一个自欺欺人的“虚荣指标”，真正照魔镜的是**留存率 (Retention Rate)**。
+用户增长不代表成功，能留住用户才是核心价值。留存率（Retention）衡量了用户在特定时间后回访的比例。
-
+
-### 4.1 留存的衰减断崖
+### 4.1 核心时间窗口
+- **次日留存 (Day 1)**：关注“第一印象”。用户首次进入后的 24 小时内是否感受到了核心价值？
+- **7日留存 (Day 7)**：关注“习惯养成”。用户是否在第一周内形成了周期性使用的习惯？
+- **30日留存 (Day 30)**：关注“长期粘性”。它决定了产品的生存上限。
-留存告诉我们一个真相：在一群人经历狂欢般地第一天疯狂下载使用后，第二天还有多少人记得登录（次日留存），一周后有多少人形成了习惯（7日留存），一个月以后还有没有哪怕是一小撮顽固信徒在这个平台扎根（30日留存）？
-
-这不仅代表着你的产品是不是在玩一场昂贵的拉新骗局。甚至，如果留存跌破 15%，你拉多少人进来都是一场注定向深渊下坠的徒劳。寻找产品初期的破局点（Aha Moment，啊哈时刻），就等于是如何拯救那条惨不忍睹的跌落生命线。
+### 4.2 留存曲线的形态：判定 PMF
+- **持续跌落至零**：说明产品没有解决用户痛点，或者获取了错误的用户群体。
+- **趋于平稳（长尾）**：说明产品已经获得了 **PMF (Product-Market Fit)**，拥有了一群忠实粘性用户，具备了规模化扩张的基础。
---
-## 5. 总结：培养向事实低头的直觉
+## 5. 结语：建立科学的数据直觉
-**数据从不撒谎，但人经常说谎。**
+优秀的分析师应当具备批判性思维，不被表象误导：
+1. **看分布而不仅看均值**：思考数据背后的差异性和离群值。
+2. **看局部而不仅看总量**：通过多维聚合（Group By）还原真实场景。
+3. **看趋势而不仅看时点**：通过留存曲线观察产品的长期健康度。
+4. **寻找断层而非盲目优化**：通过漏斗定位真正的业务瓶颈。
-一个优秀的数据大脑不是为了用漂亮的术语去忽悠领导或投资人，而是像医生看化验单一样寻找最深刻的根源：
-1. **寻找异常**：当极差和标准差大幅波动的那些黑天鹅夜晚，到底发生了什么？
-2. **切分颗粒**：用 GROUP BY 不停地顺藤摸瓜，用上帝视角将整体拆成碎片寻找突破。
-3. **定位断崖**：盯着那流血满地的转化漏斗，寻找最薄弱的环节去对症下药。
-4. **守住生命线**：不再为每天短暂飙升的流量叫好，只紧盯留存在一个月后的真实忠诚。
-
-这，就是一个真正的破冰者手起刀落的数据修行。
+数据分析的目标不是生成漂亮的报告，而是将“不确定性”降至最低，做出基于事实的明智决策。
+test
diff --git a/docs/zh-cn/appendix/5-data/data-tracking.md b/docs/zh-cn/appendix/5-data/data-tracking.md
index 925418b..4845db9 100644
--- a/docs/zh-cn/appendix/5-data/data-tracking.md
+++ b/docs/zh-cn/appendix/5-data/data-tracking.md
@@ -1,136 +1,221 @@
-# 数据埋点：数字化帝国的全视之眼
+# 数据埋点：记录用户在应用中做了什么
-::: tip 🎯 核心问题
-**如果看不见用户，我们要怎么做业务？**
+::: tip 🎯 本章要解决的问题
+**我们怎么知道用户在应用里做了什么？**
-每天有 100 万人登录你的应用，但如果没有埋点，你面对的就像是 100 万个飘忽不定的黑箱幽灵。你不知道他们点击了什么，不知道他们在哪里离开，更不知道他们为什么不买单。
+想象你开了一家线下奶茶店。你可以站在柜台后面，亲眼观察每位顾客：他们走进来先看了菜单多久？点了哪款饮品？有没有犹豫后放弃离开？
-这个看似极其抽象的词汇——"埋点"（Event Tracking），其实就是在用户必经之路上安插"隐形探头"。本章，我们将不讲枯燥的大数据黑话，而是顺着**"画出监控图纸 -> 规范笔录格式 -> 装车寄送包裹 -> 海关质检入库"**这条主线，带你零基础看清海量用户行为是如何一步步被抓取、清洗，并最终变成报表上的黄金的。
+但如果你的"店铺"是一个手机 App 或网站，你无法亲眼看到用户的操作。这时候就需要一种技术手段，在应用的关键位置"埋"下记录点，自动帮你记录用户的每一步操作。这就是**数据埋点（Event Tracking）**。
+
+"埋点"这个词听起来很专业，但它的核心思路很简单：**在用户可能操作的地方，放一个"记录器"，把用户做了什么记下来。**
+
+本章将分四步讲解这个过程：
+
+1. **选择采集方案** — 决定在哪里放记录器、怎么放
+2. **设计数据格式** — 决定每条记录应该包含哪些信息
+3. **传输与缓存** — 把记录从用户手机安全送到服务器
+4. **清洗与入库** — 整理数据，去掉重复和错误，存入数据库
:::
---
-## 第一步：画出监控图纸 (采集方案选择)
+## 第一步：选择采集方案 — 在哪里放记录器？
-**目标**：决定在产品的哪些角落，使用什么样的手段安放"监控探头"。
+**目标**：决定用什么方式来记录用户的操作。
-当产品经理想要知道"到底有多少人点击了购买按钮"时，程序员第一步要做的，就是去代码里埋下采集器。但这就像在商场里装监控，你是紧紧盯着收银台，还是无死角地布满整个商场？
+举个例子：产品经理想知道"有多少用户点击了购买按钮"。要回答这个问题，开发者需要在"购买按钮"的代码里加上一段记录逻辑 — 每当用户点击这个按钮，就自动记一笔。
+
+但这里有一个选择题：我们是**只在重要的地方放记录器**（比如只记录"购买"和"注册"），还是**在所有地方都放记录器**（记录用户的每一次点击、滑动、停留）？
+
+不同的选择，对应不同的埋点方案。
-**💡 核心原理解析：三大埋点流派**
+**💡 三种主流的埋点方式**
-目前业界在经历了不断的摩擦和演进后，确定了三种最主流的探头安放方式：
+行业中常用的埋点方案有三种，各有优劣：
-- **代码埋点 (Code Tracking)：最精准的狙击枪**
- 程序员深入到最核心的业务代码内部，当用户真正点击"购买"按下确定的那一刹那，手动写下一行拦截代码。
- *优势*：它可以顺藤摸瓜，把你兜里的余额、优惠券编号一并死死抓走发给服务器。这是所有核心业务（如支付、注册）的唯一依靠。
- *代价*：每加一个埋点都要等下一次 App 发版，极其缓慢笨重。
-- **可视化埋点 (Visual Tracking)：产品经理的魔法棒**
- 通过在手机屏幕上蒙上一层可视化的透明层，产品经理直接在屏幕上画个框："凡是点这个框的人，都给我记下来。"
- *优势*：极度快捷，完全不需要程序员写代码，所见即所得。
- *代价*：它只能抓到"表面点击"，无法获取内存深处的订单号等深度信息。
-- **全埋点 (Auto Tracking)：无死角的超级雷达**
- 直接在 App 里塞入一个"核弹级"的 SDK，它会像吸尘器一样把你点击的长宽高等所有屏幕动作统统暴力记录。
- *优势*：绝对不会漏掉任何一个角落的行为。
- *代价*：数据量如同雪花般庞大，无用的噪音极多，极其考验后期的算力和清洗能力。
+**方式一：代码埋点（Code Tracking）— 手动精确记录**
-**这一步完成了什么？** 我们成功在用户的手机里埋下了探头，只要用户有动作，探头就会被触发。
+开发者在代码中手动指定：当用户做了某个操作时，记录一条数据。
-**但问题来了**：探头虽然抓到了动作，如果每个探头都按自己的心情随便乱写信息（有的写中文，有的写英文，有的不写时间），服务器拿到后根本无法阅读。下一步，我们需要规定一套极其严格的书写规范。
+打个比方：这就像在奶茶店的收银台专门安排一个人，只记录"谁买了什么、花了多少钱"。记录的信息非常详细和准确。
+
+- *优势*：可以记录非常详细的业务信息，比如用户用了哪张优惠券、账户余额是多少
+- *代价*：每增加一个新的记录点，都需要开发者写代码、测试、发布新版本，流程较长
+
+**方式二：可视化埋点（Visual Tracking）— 点击圈选记录**
+
+不需要写代码。系统提供一个可视化工具，运营人员可以直接在应用界面上"圈选"想要监测的按钮或区域，系统自动开始记录。
+
+打个比方：这就像在奶茶店的监控画面上，用鼠标框选"收银台区域"，系统就自动开始统计这个区域的人流量。
+
+- *优势*：不需要开发者参与，运营人员自己就能配置，效率很高
+- *代价*：只能记录"用户点了什么"这类界面操作，无法记录"订单金额"等深层业务数据
+
+**方式三：全埋点（Auto Tracking）— 自动记录一切**
+
+在应用中集成一个 SDK（可以理解为一个"工具包"），它会自动记录用户的所有操作：每一次点击、每一次滑动、在每个页面停留了多久。
+
+打个比方：这就像在奶茶店的每个角落都装上摄像头，记录顾客的一举一动。
+
+- *优势*：不会遗漏任何操作，覆盖最全面
+- *代价*：数据量非常大，其中很多是无用信息（比如用户无意识的滑动），后续需要花大量精力筛选和清理
+
+**本步小结**：选好了埋点方式后，我们的应用就具备了"记录用户操作"的能力。
+
+**但这里有一个新问题**：记录器虽然能捕获到用户的操作，但如果每个记录器记下来的格式都不一样（比如有的写"用户ID"，有的写"userID"，有的干脆没记），后续就没法统一分析。所以下一步，我们需要规定一个统一的记录格式。
---
-## 第二步：规范笔录格式 (事件与数据模型)
+## 第二步：设计数据格式 — 每条记录应该包含什么？
-**上一步完成了**：我们已经在客户端选择了合适的探头（如代码埋点），成功拦截到了用户的点击动作。
+**前置条件**：我们已经选好了埋点方式（比如代码埋点），应用已经能够捕获用户的操作了。
-**这一步要实现**：让所有探头都必须使用一种统一结构化的格式，把数据汇报给服务器。
+**本步目标**：规定一个统一的"记录模板"，让所有埋点记录的格式保持一致。
-**目的**：把全世界最复杂的、因人而异的操作，全部降维、拍扁成一张清清爽爽的数据明细表。
+**为什么需要统一格式？** 想象一下：如果奶茶店有三个店员同时记录销售情况，一个写"小明买了珍珠奶茶 15 元"，另一个写"15，奶茶，珍珠"，第三个写"珍珠奶茶一杯"。到了月底汇总的时候，这些记录格式完全不同，整理起来会非常痛苦。所以我们需要一张统一的"记录表"，规定每条记录必须填写哪些栏位。
-**💡 核心原理解析：4W1H 数据模型**
+**💡 核心原理：4W1H 记录模板**
-不管你用什么语言开发，这团数据到了服务器门口，就必须回答出极其关键的 `4W1H` 灵魂拷问。你可以把它看作一份给警察局的审讯笔录：
+无论记录什么操作，每条数据都需要回答以下五个问题（简称 4W1H）：
-- **Who (是谁 - user_id/device_id)**：这简直是最核心的部分。如果用户没登录，我们就抓他手机底层的 MAC 地址或 UUID（设备指纹）；如果登录了，就死死绑定他的 `user_id`。
-- **When (何时 - timestamp)**：精确到毫秒的时间戳。特别注意，针对跨国业务，必须强制换算成格林威治标准时间 (UTC)，否则你会看到昨天的人穿越到了明天。
-- **Where & How (何地与如何 - 公共属性)**：被统称为**公共属性 (Common Properties)**。它交代了作案环境：不管你在干什么，你的手机型号（iPhone 15）、网络环境（5G）、App 版本号（v1.2.3）都会被系统自动提取，像一个标签一样死死贴在这条数据上。
-- **What (业务详情 - 自定义属性)**：被统称为**自定义属性 (Custom Properties)**。如果你的动作是 `add_to_cart` (加入购物车)，那我们就必须自定义几个专属的细作：比如商品型号是 iPhone，价格是 7999 元。
+**Who — 谁做的？**
-**这一步完成了什么？** 这是一场混乱向秩序的妥协，我们终于拿到了一份极致规范、机器可读的 JSON 代码（就像你在上面组件模型中看到的那样）。
+我们需要知道这条记录是哪个用户产生的。
-**但问题来了**：一份标准的 JSON 准备好了。但如果是双十一，一秒钟有一万个人点击了加入购物车。如果我们让手机直接一秒钟发一万次请求给远方的数据库，数据库瞬间就会被这股洪水打穿融化，手机电量也会瞬间耗尽。下一步，我们要解决运输问题。
+- 如果用户已经登录，就用他的账号 ID（比如 `user_id: "zhangsan123"`）
+- 如果用户没有登录，就用设备的唯一标识（比如手机的设备编号），这样至少能区分"这是同一台手机上的操作"
+
+**When — 什么时候做的？**
+
+记录操作发生的精确时间，精确到毫秒。
+
+这里有一个细节：如果你的应用有海外用户，北京时间下午 3 点和纽约时间下午 3 点其实差了 13 个小时。为了避免混乱，所有时间统一转换为 UTC 标准时间（可以理解为"世界统一时间"）。
+
+**Where & How — 在什么环境下做的？**
+
+这部分记录用户操作时的设备和网络环境，称为**公共属性**。之所以叫"公共"，是因为无论用户做了什么操作，这些信息都会自动附带上去。例如：
+
+- 设备型号：iPhone 15 / 小米 14
+- 网络类型：WiFi / 5G / 4G
+- App 版本号：v1.2.3
+- 操作系统：iOS 18 / Android 15
+
+这些信息的价值在于：如果发现某个 Bug 只在特定机型上出现，公共属性可以帮助快速定位问题。
+
+**What — 具体做了什么？**
+
+这部分记录操作的具体业务细节，称为**自定义属性**。不同的操作需要记录不同的信息。例如：
+
+- 用户点击"加入购物车"：需要记录商品名称、商品价格、商品数量
+- 用户完成支付：需要记录订单金额、支付方式、优惠券编号
+
+**本步小结**：通过 4W1H 模板，我们把用户的每一个操作都转化成了一条格式统一的数据记录。在技术实现中，这条记录通常以 JSON 格式存储（JSON 是一种通用的数据格式，上方的交互组件展示了它的样子）。
+
+**但这里又有一个新问题**：数据格式统一了，但如果应用的用户量很大（比如促销活动期间，每秒钟可能产生上万条记录），用户手机不可能每产生一条记录就立刻发送一次 — 这样既费电又费流量，服务器也扛不住。所以下一步，我们需要设计一个更聪明的传输方式。
---
-## 第三步：装车与寄送包裏 (本地缓存与管道传输)
+## 第三步：传输与缓存 — 怎么把数据安全送到服务器？
-**上一步完成了**：我们将用户行为封装成了标准的、带有时间戳和属性的格式化数据块。
+**前置条件**：用户的每个操作已经被记录成了格式统一的 JSON 数据。
-**这一步要实现**：确保数据在极端的弱网、高并发等恶劣环境下，能够安全、不翻车地送达公司的服务器。
+**本步目标**：把这些数据从用户的手机（或浏览器）可靠地传输到我们的服务器，即使在网络不好的情况下也不丢数据。
-**目的**：通过缓存和攒批机制，保护用户的手机电量，同时拯救公司脆弱的数据库。
+**为什么不能直接发送？** 如果每产生一条记录就立刻发一次网络请求，就像每写一封信就跑一趟邮局一样 — 效率太低了。更合理的做法是：攒一批信，一次性送过去。
-**💡 核心原理解析：漫长而致命的数据长征**
+**💡 核心原理：数据传输的三道保障**
-数据绝不是“点一下按钮，就嗖地一声飞进数据库”的。在它真正被数据分析师查到之前，它在黑暗的管道中经历了一场你无法想象的跋涉：
+数据从用户手机到服务器，需要经过三道保障机制，确保既高效又不丢数据：
-1. **装车攒批 (Batching)**：SDK 本质上是个老司机，它绝不会拿到一个包裹就发车。它会把用户的点击行为死死扣留在手机内存里。直到积攒了 30 条数据，或者熬过了 5 秒钟的倒计时，它才会把它们压缩成一个大包裹一次性掷出。这样不仅省流量，更是省下了几十倍的 HTTP 网络握手开销。
-2. **断网地堡 (本地存储)**：如果你刚好走进电梯或者高铁进入隧道，网络断了怎么办？这口数据如果在内存里，App 一关就灰飞烟灭了。所以埋点 SDK 在发车前，必须把数据悄悄写进手机的 SQLite 或者 IndexedDB 硬盘缓存中。即使手机没电关机了，一个月后你重新连上 WiFi，它也会像诈尸一般疯狂补发。
-3. **削峰填谷 (消息队列)**：当大包裹终于跨越太平洋抵达公司网关时，服务器仍旧不敢直接把它写进硬盘。所有的包裹都会被全数接入卡夫卡（Kafka）等**消息队列**的汪洋大海中。无论流量多么残暴，消息队列都会温柔地将其吸收，然后像涓涓细流一样，慢慢排队喂给后端的数据库。
+**第一道：攒一批再发（批量聚合）**
-**这一步完成了什么？** 历经千难万险，无数个封装好的 JSON 包裹，终于安全平稳地度过了网络高峰，抵达了后端机房。
+SDK（埋点工具包）不会每产生一条记录就发送一次，而是先把记录暂存在手机内存里。当攒够一定数量（比如 30 条），或者等待超过一定时间（比如 5 秒），再把这一批数据打包，一次性发送出去。
-**但问题来了**：包裹虽然到了，但在客户端疯狂的断点续传甚至重试机制下，我们极大概率会收到两份完全一样的双胞胎数据。直接存起来，财务看到报表会当场崩溃（销售额翻倍的假象）。下一步，必须进行海关重重清洗。
+这就像寄快递：你不会买一件东西就跑一趟快递站，而是攒几件一起寄，省时省力。对手机来说，这样做能减少网络请求次数，省电省流量。
+
+**第二道：断网也不丢（本地存储）**
+
+用户在电梯里、地铁隧道中，手机经常没有网络信号。如果数据只存在内存里，用户一关闭 App，数据就没了。
+
+所以 SDK 会把还没发送的数据存到手机的本地存储中（类似于把信先放进抽屉）。等网络恢复后，再自动把这些数据补发出去。这样即使用户短暂断网，数据也不会丢失。
+
+**第三道：服务器不被压垮（消息队列）**
+
+数据到达服务器后，并不会直接写入数据库。为什么？因为在促销活动等高峰期，可能每秒有几万条数据同时涌入，数据库如果直接处理这么大的量，可能会崩溃。
+
+解决方案是在中间加一个"缓冲区"，技术上叫**消息队列**（常用的工具叫 Kafka）。它的作用就像餐厅的取号排队系统：高峰期顾客（数据）先排队等候，厨房（数据库）按自己的节奏一个一个处理，不会被同时涌入的订单压垮。
+
+**本步小结**：通过"攒一批再发 → 断网本地存储 → 消息队列缓冲"这三道保障，数据已经安全抵达了服务器。
+
+**但还有一个问题**：因为断网重连后会自动补发数据，同一条记录有可能被发送了两次。如果不处理就直接存入数据库，数据就会重复（比如一笔 100 元的订单被记成了两笔，销售额就虚高了）。所以下一步，我们需要对数据进行"清洗"。
---
-## 第四步：海关质检与入库 (ETL 清洗)
+## 第四步：清洗与入库 — 整理数据，去掉"脏数据"
-**上一步完成了**：数据安全度过了网络拥堵，平稳地来到了后端服务器的内存里。
+**前置条件**：数据已经通过传输管道安全抵达服务器。
-**这一步要实现**：剔除水分和杂质，把原本泥沙俱下的原石，提炼成绝对纯净的数据金条。
+**本步目标**：在数据正式存入数据库之前，先做一次"体检"— 去掉重复的、修复格式有问题的，确保最终存储的数据干净、准确。
-**目的**：确保入库的数据无重复、无错漏，供分析师直接查询使用。
+**为什么需要清洗？** 就像收到一箱快递后，你需要检查一下：有没有重复发货的？有没有发错的？有没有包装破损的？数据也是一样，直接存入数据库之前，需要先检查和整理。
+
+这个过程在技术上叫做 **ETL**，是三个英文单词的缩写：
+- **E**xtract（提取）：从消息队列中取出数据
+- **T**ransform（转换）：检查和修复数据格式
+- **L**oad（加载）：把清洗好的数据写入数据库
-**💡 核心原理解析：ETL (提取、转换、加载) 提纯车间**
+**💡 核心原理：清洗数据的两个关键动作**
-数据在最终落入冰冷的 ClickHouse 或 Hive 这样的庞大**数据仓库 (Data Warehouse)** 之前，需要经历最后一道关卡——数据清洗室。
+**动作一：去重 — 去掉重复的记录**
-- **无情的去重杀手 (De-duplication)**：
- 因为手机网络很差，可能第一次发出了包裹，但没收到服务器的回复，手机以为没发成功，就又发了一遍。服务器怎么辨别？
- 答案是在第一步打包时，手机就给每一条数据生成了一个极其唯一的 `dedup_id` (比如全球唯一的 UUID)。服务器清洗站有一个滤网，看到同样的 ID，直接把第二条丢进垃圾桶，保证数据绝对唯一。
-- **修剪畸形儿 (Validation & Transformation)**：
- 早期版本 App 发来的数据可能是 `userId`，而最新版叫 `user_id`。如果带着这种混乱入库会导致灾难。此时在这里必须写脚本强制把它们全部对齐。发现有的时间戳是未来时间？抛弃！发现有的国家代码写了外星文字？直接打上 `unknown`。
+前面提到，断网重连后 SDK 会自动补发数据，这可能导致同一条记录被发送了多次。怎么识别哪些是重复的？
-**这一步完成了什么？** 沙子被洗成了真金。这些被抚平了所有褶皱、格式统一、完美无缝的数据，终于静静地躺在了数据仓库里。只需分析师一句 `SELECT * FROM events` 的 SQL 召唤，它们就会在 0.1 秒内呈现出人类群体最深的奥秘。
+方法很简单：在客户端打包数据时，给每条记录分配一个全球唯一的编号（叫做 `dedup_id`，类似于快递单号）。服务器在存储数据前，先检查这个编号是否已经存在 — 如果已经存在，说明是重复数据，直接丢弃。
+
+**动作二：校验与格式统一 — 修复不规范的记录**
+
+应用会不断更新版本，不同版本的埋点代码可能存在细微差异。比如：
+
+- 旧版本把用户 ID 字段命名为 `userId`，新版本改成了 `user_id`
+- 某些记录的时间戳明显不合理（比如显示为 1970 年）
+- 某些字段的值无法识别
+
+在这一步，系统会编写转换规则来统一处理这些问题：字段名不一致的统一对齐，时间戳异常的记录予以丢弃，无法识别的值标记为 `unknown`。
+
+**本步小结**：经过去重和格式校验后，数据以干净、统一的形式写入**数据仓库**（一种专门用于存储和分析大量数据的数据库，常见的有 ClickHouse、Hive 等）。数据分析师可以直接用 SQL 语句查询这些数据，获得可靠的分析结果。
---
## 完整流程回顾
-让我们把整个万里长征串联起来看一看：
+以下是数据埋点从采集到入库的四步流程总结：
-| 步骤 | 行动 | 完成了什么 | 下一步我们需要解决 |
-|------|-----------|---------------|----------------|
-| **1. 采集方案选择** | 决定用代码还是全埋点 | 在客户端深处安插了吸取操作的探头 | 探头抓到的数据像乱码一样，需要规范 |
-| **2. 事件与数据模型** | 建立 4W1H 模板 | 将乱码收敛为格式完美的极简 JSON | 手机网络极端脆弱，没法立刻发这么标准的数据 |
-| **3. 数据管道与缓存** | 缓冲攒批，重试补传 | 保证数据扛住了电梯断网和双十一洪峰 | 安全抵达但可能存在重复发包的脏数据 |
-| **4. ETL 清洗入库** | 去除重复、修复乱码 | ✅ 落入数据仓库，变成 BI 报表上的增长金条 | （完美结束，开始分析数据反哺商业） |
+| 步骤 | 做了什么 | 得到了什么 | 还剩什么问题 |
+|------|----------|-----------|-------------|
+| **1. 选择采集方案** | 决定用哪种方式记录用户操作 | 应用具备了记录能力 | 各记录器的数据格式不统一 |
+| **2. 设计数据格式** | 用 4W1H 模板统一记录格式 | 每条记录都是标准的 JSON | 用户量大时逐条发送扛不住 |
+| **3. 传输与缓存** | 攒批发送、断网存储、队列缓冲 | 数据安全抵达服务器 | 重试可能导致数据重复 |
+| **4. 清洗与入库** | 去重、校验、格式统一 | ✅ 干净的数据存入数据仓库 | — |
---
-## 结语：不可见的地下长城
+## 结语
-当我们点一下外卖的付款界面的那 1 毫秒内，我们几乎感觉不到任何的波动甚至是迟滞。
+当用户在应用中点击一个按钮时，表面上只是一个瞬间的动作。但在这背后，一条完整的数据链路已经开始运转：
-但此时此刻，这段包含了你买的黄焖鸡、花了 20 元、用着一台 iPhone 的微小包裹，正在你的手机后台默默组装。它也许潜伏在内存里等了 3 秒钟，随后化作一段无线电波飞向基站，在光纤中跨越几百个路由器，抵达了网关机房，随后被吸入消息队列排队、被清洗掉一切污垢，最终永久固化在一块闪烁着冷光的磁盘扇区深处。
+1. 埋点代码捕获到这次点击，按照 4W1H 模板生成一条标准记录
+2. 记录被暂存在手机本地，攒够一批后统一发送到服务器
+3. 服务器通过消息队列平稳接收，再经过去重和格式校验
+4. 最终，一条干净、准确的数据被写入数据仓库
-正是这种从“采集 -> 建模 -> 传输 -> 清洗”长达千万里的坚固体系，用一根根最枯燥的数据流水线，反向拼凑出了商业世界上极度生动、甚至比你自己还要了解你自己的用户画像图腾。这，就是代码之外最伟大的工程之一。
+这就是数据埋点的完整过程。它把用户分散的、看不见的操作行为，转化成了可以查询、可以分析的结构化数据。产品经理可以据此了解用户喜欢什么功能、在哪里流失；运营人员可以评估活动效果；开发者可以定位问题出现在哪个版本。
+
+这套"采集 → 建模 → 传输 → 清洗"的体系，是数据驱动决策的基础设施。
diff --git a/find-intervals.mjs b/find-intervals.mjs
index 28acd53..9295fe0 100644
--- a/find-intervals.mjs
+++ b/find-intervals.mjs
@@ -2,10 +2,12 @@ import fs from 'fs'
import path from 'path'
function walkSync(dir, filelist = []) {
- fs.readdirSync(dir).forEach(file => {
+ fs.readdirSync(dir).forEach((file) => {
const dirFile = path.join(dir, file)
try {
- filelist = fs.statSync(dirFile).isDirectory() ? walkSync(dirFile, filelist) : filelist.concat(dirFile)
+ filelist = fs.statSync(dirFile).isDirectory()
+ ? walkSync(dirFile, filelist)
+ : filelist.concat(dirFile)
} catch (err) {
if (err.code === 'OOM' || err.code === 'EMFILE') throw err
}
@@ -13,7 +15,9 @@ function walkSync(dir, filelist = []) {
return filelist
}
-const vueFiles = walkSync('docs/.vitepress/theme/components').filter(f => f.endsWith('.vue'))
+const vueFiles = walkSync('docs/.vitepress/theme/components').filter((f) =>
+ f.endsWith('.vue')
+)
for (const file of vueFiles) {
const content = fs.readFileSync(file, 'utf8')
diff --git a/find_setinterval.cjs b/find_setinterval.cjs
index 665d3d5..d6e57b0 100644
--- a/find_setinterval.cjs
+++ b/find_setinterval.cjs
@@ -1,52 +1,54 @@
-const fs = require('fs');
-const path = require('path');
+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;
+ 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');
+const vueFiles = walk('docs/.vitepress/theme/components')
-vueFiles.forEach(file => {
- const lines = fs.readFileSync(file, 'utf8').split('\n');
- let bracketDepth = 0;
- let insideScript = false;
+vueFiles.forEach((file) => {
+ const lines = fs.readFileSync(file, 'utf8').split('\n')
+ let bracketDepth = 0
+ let insideScript = false
- lines.forEach((line, index) => {
- if (line.includes('')) {
+ insideScript = false
+ }
- if (insideScript) {
- // Check for setInterval BEFORE updating bracket depth for the current line
- // because `setInterval(() => {` will increase depth but the call ITSELF is at depth 0
- if (line.includes('setInterval') && bracketDepth === 0) {
- console.log(`Top-level setInterval: ${file}:${index + 1} - ${line.trim()}`);
- }
+ if (insideScript) {
+ // Check for setInterval BEFORE updating bracket depth for the current line
+ // because `setInterval(() => {` will increase depth but the call ITSELF is at depth 0
+ if (line.includes('setInterval') && bracketDepth === 0) {
+ console.log(
+ `Top-level setInterval: ${file}:${index + 1} - ${line.trim()}`
+ )
+ }
- // Simple Bracket Depth Counting
- // Handle one-liners like `if (x) { ... }` natively by adding/subtracting on the same line
- // Wait, we only care about trailing brackets basically. Ignore string contents for simplicity.
- // This heuristic is usually fine for formatting standard vue codes
- const openCount = (line.match(/\{/g) || []).length;
- const closeCount = (line.match(/\}/g) || []).length;
- bracketDepth += openCount - closeCount;
- }
- });
-});
+ // Simple Bracket Depth Counting
+ // Handle one-liners like `if (x) { ... }` natively by adding/subtracting on the same line
+ // Wait, we only care about trailing brackets basically. Ignore string contents for simplicity.
+ // This heuristic is usually fine for formatting standard vue codes
+ const openCount = (line.match(/\{/g) || []).length
+ const closeCount = (line.match(/\}/g) || []).length
+ bracketDepth += openCount - closeCount
+ }
+ })
+})
diff --git a/find_top_level_setinterval.js b/find_top_level_setinterval.js
index 7c201da..84b46c4 100644
--- a/find_top_level_setinterval.js
+++ b/find_top_level_setinterval.js
@@ -1,59 +1,61 @@
-const fs = require('fs');
-const path = require('path');
-const compiler = require('vue/compiler-sfc');
-const babel = require('@babel/parser');
-const traverse = require('@babel/traverse').default;
+const fs = require('fs')
+const path = require('path')
+const compiler = require('vue/compiler-sfc')
+const babel = require('@babel/parser')
+const traverse = require('@babel/traverse').default
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;
+ 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');
+const vueFiles = walk('docs/.vitepress/theme/components')
-vueFiles.forEach(file => {
- const content = fs.readFileSync(file, 'utf8');
- if (!content.includes('setInterval')) return;
- const { descriptor } = compiler.parse(content);
- if (!descriptor.scriptSetup) return;
-
- const ast = babel.parse(descriptor.scriptSetup.content, {
- sourceType: 'module',
- plugins: ['typescript']
- });
+vueFiles.forEach((file) => {
+ const content = fs.readFileSync(file, 'utf8')
+ if (!content.includes('setInterval')) return
+ const { descriptor } = compiler.parse(content)
+ if (!descriptor.scriptSetup) return
- traverse(ast, {
- CallExpression(path) {
- if (path.node.callee.name === 'setInterval') {
- // check if we are inside a function declaration or arrow function or onMounted check
- let parent = path.parentPath;
- let insideFunction = false;
- while (parent) {
- if (
- parent.isFunctionDeclaration() ||
- parent.isArrowFunctionExpression() ||
- parent.isFunctionExpression() ||
- parent.isObjectMethod()
- ) {
- insideFunction = true;
- break;
- }
- parent = parent.parentPath;
- }
- if (!insideFunction) {
- console.log(`Top-level setInterval found in ${file} at line ${path.node.loc.start.line}`);
- }
- }
+ const ast = babel.parse(descriptor.scriptSetup.content, {
+ sourceType: 'module',
+ plugins: ['typescript']
+ })
+
+ traverse(ast, {
+ CallExpression(path) {
+ if (path.node.callee.name === 'setInterval') {
+ // check if we are inside a function declaration or arrow function or onMounted check
+ let parent = path.parentPath
+ let insideFunction = false
+ while (parent) {
+ if (
+ parent.isFunctionDeclaration() ||
+ parent.isArrowFunctionExpression() ||
+ parent.isFunctionExpression() ||
+ parent.isObjectMethod()
+ ) {
+ insideFunction = true
+ break
+ }
+ parent = parent.parentPath
}
- });
-});
+ if (!insideFunction) {
+ console.log(
+ `Top-level setInterval found in ${file} at line ${path.node.loc.start.line}`
+ )
+ }
+ }
+ }
+ })
+})