diff --git a/README.md b/README.md
index c9b55f9..49c3590 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
 # Easy-Vibe : Learn vibe coding from 0 to 1
 
 <p align="center">
-  📌 <a href="https://datawhalechina.github.io/easy-vibe/">开始在线阅读 (Start Reading Online)</a>
+  📌 <a href="https://datawhalechina.github.io/easy-vibe/">在线阅读 (Read Online)</a> · ✨ <a href="https://datawhalechina.github.io/easy-vibe/zh-cn/appendix/prompt-engineering.html">交互式教程 (Interactive Tutorial)</a>
 </p>
 
 <p align="center">
@@ -49,6 +49,57 @@
 
 </div>
 
+<table align="center">
+  <tr>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/gif-header.png" width="100%">
+      <br>
+      <strong>新手专属学习地图</strong>
+      <br>
+      <sub>零基础专属指引，清晰规划路径，告别“学了忘”</sub>
+    </td>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/gif-tutorial.png" width="100%">
+      <br>
+      <strong>手把手图文教程</strong>
+      <br>
+      <sub>保姆级图文详解，如同私教在旁，跟着做就能学会</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/gif-ide.gif" width="100%">
+      <br>
+      <strong>沉浸式模拟编程</strong>
+      <br>
+      <sub>虚拟鼠标自动导览，带你快速上手 IDE 核心用法</sub>
+    </td>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/gif-diffusion.gif" width="100%">
+      <br>
+      <strong>看得见的 AI 原理</strong>
+      <br>
+      <sub>算法原理动画化，一眼看懂 AI 如何“画”出图片</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/gif-rag.gif" width="100%">
+      <br>
+      <strong>像玩游戏一样学 RAG</strong>
+      <br>
+      <sub>独家交互组件，点击即可看清 RAG 数据流向</sub>
+    </td>
+    <td width="50%" valign="top" align="center">
+      <img src="assets/git-terminal.gif" width="100%">
+      <br>
+      <strong>可视化终端原理</strong>
+      <br>
+      <sub>命令行操作可视化，直观展示后台逻辑与原理</sub>
+    </td>
+  </tr>
+</table>
+
 ---
 
 在 AI 时代，把想法变成产品的人，往往技术不是最强，而是最先迈出行动。
diff --git a/assets/gif-diffusion.gif b/assets/gif-diffusion.gif
new file mode 100644
index 0000000..7165579
Binary files /dev/null and b/assets/gif-diffusion.gif differ
diff --git a/assets/gif-header.png b/assets/gif-header.png
new file mode 100644
index 0000000..ad744c7
Binary files /dev/null and b/assets/gif-header.png differ
diff --git a/assets/gif-ide.gif b/assets/gif-ide.gif
new file mode 100644
index 0000000..49380b3
Binary files /dev/null and b/assets/gif-ide.gif differ
diff --git a/assets/gif-rag.gif b/assets/gif-rag.gif
new file mode 100644
index 0000000..e697b7e
Binary files /dev/null and b/assets/gif-rag.gif differ
diff --git a/assets/gif-tutorial.png b/assets/gif-tutorial.png
new file mode 100644
index 0000000..376daf2
Binary files /dev/null and b/assets/gif-tutorial.png differ
diff --git a/assets/gif-tutorial2.png b/assets/gif-tutorial2.png
new file mode 100644
index 0000000..947eee9
Binary files /dev/null and b/assets/gif-tutorial2.png differ
diff --git a/assets/git-terminal.gif b/assets/git-terminal.gif
new file mode 100644
index 0000000..0adca3a
Binary files /dev/null and b/assets/git-terminal.gif differ
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index ba19b3f..78afe69 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -538,10 +538,6 @@ export default defineConfig({
                   text: '提示词工程',
                   link: '/zh-cn/appendix/prompt-engineering'
                 },
-                {
-                  text: '上下文工程',
-                  link: '/zh-cn/appendix/context-engineering'
-                },
                 {
                   text: '人工智能进化史',
                   link: '/zh-cn/appendix/ai-evolution'
@@ -553,6 +549,10 @@ export default defineConfig({
                   link: '/zh-cn/appendix/image-gen-intro'
                 },
                 { text: 'AI 音频模型', link: '/zh-cn/appendix/audio-intro' },
+                {
+                  text: '上下文工程',
+                  link: '/zh-cn/appendix/context-engineering'
+                },
                 { text: 'Agent 智能体', link: '/zh-cn/appendix/agent-intro' },
                 {
                   text: 'AI 能力词典',
@@ -561,7 +561,7 @@ export default defineConfig({
               ]
             },
             {
-              text: 'Web 基础',
+              text: '前端开发',
               collapsed: false,
               items: [
                 {
@@ -580,14 +580,6 @@ export default defineConfig({
                   text: 'Canvas 2D 入门',
                   link: '/zh-cn/appendix/canvas-intro'
                 },
-                {
-                  text: '后端进化史',
-                  link: '/zh-cn/appendix/backend-evolution'
-                },
-                {
-                  text: '后端编程语言',
-                  link: '/zh-cn/appendix/backend-languages'
-                },
                 {
                   text: 'URL 到浏览器显示',
                   link: '/zh-cn/appendix/url-to-browser'
@@ -599,30 +591,38 @@ export default defineConfig({
               ]
             },
             {
-              text: '开发基础',
+              text: '后端开发',
               collapsed: false,
               items: [
-                { text: 'IDE 原理', link: '/zh-cn/appendix/ide-intro' },
-                { text: '终端入门', link: '/zh-cn/appendix/terminal-intro' },
-                { text: 'Git 详细介绍', link: '/zh-cn/appendix/git-intro' },
-                { text: '数据库原理', link: '/zh-cn/appendix/database-intro' },
                 {
-                  text: '计算机网络',
-                  link: '/zh-cn/appendix/computer-networks'
+                  text: '后端进化史',
+                  link: '/zh-cn/appendix/backend-evolution'
                 },
-                { text: '部署与上线', link: '/zh-cn/appendix/deployment' }
-              ]
-            },
-            {
-              text: '后端进阶',
-              collapsed: false,
-              items: [
+                {
+                  text: '后端编程语言',
+                  link: '/zh-cn/appendix/backend-languages'
+                },
+                { text: '数据库原理', link: '/zh-cn/appendix/database-intro' },
                 { text: '系统缓存设计', link: '/zh-cn/appendix/cache-design' },
                 { text: '消息队列设计', link: '/zh-cn/appendix/queue-design' },
                 { text: '鉴权原理与实战', link: '/zh-cn/appendix/auth-design' },
                 { text: '埋点设计', link: '/zh-cn/appendix/tracking-design' },
                 { text: '线上运维', link: '/zh-cn/appendix/operations' }
               ]
+            },
+            {
+              text: '通用技能',
+              collapsed: false,
+              items: [
+                { text: 'IDE 原理', link: '/zh-cn/appendix/ide-intro' },
+                { text: '终端入门', link: '/zh-cn/appendix/terminal-intro' },
+                { text: 'Git 详细介绍', link: '/zh-cn/appendix/git-intro' },
+                {
+                  text: '计算机网络',
+                  link: '/zh-cn/appendix/computer-networks'
+                },
+                { text: '部署与上线', link: '/zh-cn/appendix/deployment' }
+              ]
             }
           ]
         }
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/AIEvolutionTimelineDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/AIEvolutionTimelineDemo.vue
new file mode 100644
index 0000000..c4d0276
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/AIEvolutionTimelineDemo.vue
@@ -0,0 +1,305 @@
+<template>
+  <div class="ai-evolution-timeline-demo">
+    <div class="timeline-container">
+      <div class="timeline-track"></div>
+
+      <div
+        v-for="(era, index) in eras"
+        :key="index"
+        class="timeline-era"
+        :class="{ active: activeEra === index }"
+        @click="activeEra = index"
+      >
+        <div class="era-marker">
+          <div class="marker-dot"></div>
+          <div class="marker-line"></div>
+        </div>
+        <div class="era-content">
+          <div class="era-year">{{ era.year }}</div>
+          <div class="era-title">{{ era.title }}</div>
+          <div class="era-desc">{{ era.desc }}</div>
+          <div class="era-examples">
+            <span
+              v-for="(example, i) in era.examples"
+              :key="i"
+              class="example-tag"
+            >
+              {{ example }}
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Era Details Panel -->
+    <transition name="fade">
+      <div v-if="activeEra !== null" class="era-details">
+        <div class="details-header">
+          <h4>{{ eras[activeEra].title }}</h4>
+          <span class="year-badge">{{ eras[activeEra].year }}</span>
+        </div>
+        <div class="details-content">
+          <p>{{ eras[activeEra].fullDesc }}</p>
+          <div class="key-points">
+            <h5>核心特点：</h5>
+            <ul>
+              <li v-for="(point, i) in eras[activeEra].keyPoints" :key="i">
+                {{ point }}
+              </li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </transition>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const activeEra = ref(0)
+
+const eras = ref([
+  {
+    year: '20世纪50-80年代',
+    title: '符号主义时代',
+    desc: '规则与逻辑推理',
+    fullDesc: '早期人工智能研究认为，智能可以通过符号和逻辑规则来表达。科学家们尝试编写大量规则来让机器模拟人类专家的决策过程。',
+    examples: ['专家系统', '深蓝', 'MYCIN'],
+    keyPoints: [
+      '人工编写 If-Then 规则',
+      '逻辑推理能力强大',
+      '可解释性强',
+      '无法处理复杂现实世界',
+      '容易遇到组合爆炸问题'
+    ]
+  },
+  {
+    year: '21世纪10年代',
+    title: '连接主义时代',
+    desc: '神经网络与深度学习',
+    fullDesc: '随着大数据和 GPU 算力的突破，深度学习迎来了春天。神经网络通过多层结构自动学习特征，在图像识别、语音识别等领域取得巨大成功。',
+    examples: ['AlexNet', 'AlphaGo', '人脸识别'],
+    keyPoints: [
+      '模仿人脑神经元结构',
+      '从数据中自动学习',
+      '强大的模式识别能力',
+      '需要海量标注数据',
+      '黑盒模型，缺乏可解释性'
+    ]
+  },
+  {
+    year: '21世纪20年代至今',
+    title: '生成式人工智能时代',
+    desc: '大模型与创造力',
+    fullDesc: 'Transformer 架构的诞生让机器理解了上下文关系。GPT 等大语言模型不仅能生成文本、图像，还展现出了惊人的推理和创造能力。',
+    examples: ['ChatGPT', 'Midjourney', 'GPT-4'],
+    keyPoints: [
+      '基于注意力机制',
+      '理解上下文和语义',
+      '能生成新内容',
+      '通用智能雏形',
+      '存在幻觉和偏见问题'
+    ]
+  }
+])
+</script>
+
+<style scoped>
+.ai-evolution-timeline-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.timeline-container {
+  position: relative;
+  padding: 2rem 0;
+}
+
+.timeline-track {
+  position: absolute;
+  left: 20px;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  background: var(--vp-c-divider);
+  border-radius: 2px;
+}
+
+.timeline-era {
+  position: relative;
+  display: flex;
+  margin-bottom: 2rem;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.timeline-era:hover {
+  opacity: 0.9;
+}
+
+.timeline-era.active .era-marker .marker-dot {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+}
+
+.era-marker {
+  position: relative;
+  width: 44px;
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  z-index: 1;
+}
+
+.marker-dot {
+  width: 16px;
+  height: 16px;
+  background: var(--vp-c-bg);
+  border-radius: 50%;
+  border: 3px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+}
+
+.marker-line {
+  flex: 1;
+  width: 2px;
+  background: var(--vp-c-divider);
+  margin-top: 4px;
+}
+
+.timeline-era:last-child .marker-line {
+  display: none;
+}
+
+.era-content {
+  margin-left: 1rem;
+  padding: 1rem 1.5rem;
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+  flex: 1;
+}
+
+.timeline-era.active .era-content {
+  border-color: var(--vp-c-brand);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.era-year {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--vp-c-text-2);
+  margin-bottom: 0.25rem;
+}
+
+.era-title {
+  font-size: 1.25rem;
+  font-weight: 700;
+  margin-bottom: 0.25rem;
+  color: var(--vp-c-text-1);
+}
+
+.era-desc {
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+  margin-bottom: 0.75rem;
+}
+
+.era-examples {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.example-tag {
+  padding: 0.25rem 0.75rem;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--vp-c-text-2);
+}
+
+.era-details {
+  margin-top: 1.5rem;
+  padding: 1.5rem;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.details-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.details-header h4 {
+  margin: 0;
+  font-size: 1.5rem;
+  color: var(--vp-c-text-1);
+}
+
+.year-badge {
+  padding: 0.5rem 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.12);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.2);
+  color: var(--vp-c-brand);
+  border-radius: 20px;
+  font-weight: 600;
+  font-size: 0.875rem;
+}
+
+.details-content p {
+  line-height: 1.8;
+  margin-bottom: 1rem;
+  color: var(--vp-c-text-2);
+}
+
+.key-points {
+  background: var(--vp-c-bg-soft);
+  padding: 1rem 1.5rem;
+  border-radius: 6px;
+  border-left: 4px solid var(--vp-c-brand);
+  border: 1px solid var(--vp-c-divider);
+}
+
+.key-points h5 {
+  margin: 0 0 0.75rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1rem;
+}
+
+.key-points ul {
+  margin: 0;
+  padding-left: 1.25rem;
+}
+
+.key-points li {
+  margin-bottom: 0.5rem;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+}
+
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/AiEvolutionDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/AiEvolutionDemo.vue
index e0af6db..537beac 100644
--- a/docs/.vitepress/theme/components/appendix/ai-history/AiEvolutionDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/ai-history/AiEvolutionDemo.vue
@@ -197,21 +197,17 @@ const stages = [
 
 <style scoped>
 .ai-evolution-demo {
-  border-radius: 16px;
-  background: var(--vp-c-bg);
-  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.05);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
   border: 1px solid var(--vp-c-divider);
   overflow: hidden;
-  margin: 2rem 0;
-  font-family:
-    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial,
-    sans-serif;
+  margin: 1rem 0;
 }
 
 /* Reusing Timeline Styles from FrontendEvolutionDemo for consistency */
 .timeline-container {
   padding: 2rem 1rem 1rem;
-  background: linear-gradient(to bottom, var(--vp-c-bg-soft), var(--vp-c-bg));
+  background: var(--vp-c-bg-soft);
   display: flex;
   justify-content: space-between;
   position: relative;
@@ -325,13 +321,7 @@ const stages = [
 .header-section h3 {
   font-size: 1.5rem;
   margin-bottom: 0.5rem;
-  background: linear-gradient(
-    120deg,
-    #10b981,
-    #3b82f6
-  ); /* Green to Blue for AI */
-  -webkit-background-clip: text;
-  -webkit-text-fill-color: transparent;
+  color: var(--vp-c-text-1);
 }
 
 .stage-index {
@@ -362,29 +352,24 @@ const stages = [
 
 .mac-window {
   border-radius: 12px;
-  border: 1px solid rgba(0, 0, 0, 0.1);
-  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.05);
+  border: 1px solid var(--vp-c-divider);
   overflow: hidden;
   display: flex;
   flex-direction: column;
-  background: white;
-  transition: transform 0.3s;
-}
-.mac-window:hover {
-  transform: translateY(-5px);
+  background: var(--vp-c-bg);
 }
 
 .concept-window {
-  background: #f8fafc;
+  background: var(--vp-c-bg);
 }
 .app-window {
-  background: white;
+  background: var(--vp-c-bg);
 }
 
 .window-bar {
   padding: 0.8rem 1rem;
-  background: white;
-  border-bottom: 1px solid rgba(0, 0, 0, 0.05);
+  background: var(--vp-c-bg-soft);
+  border-bottom: 1px solid var(--vp-c-divider);
   display: flex;
   align-items: center;
   position: relative;
@@ -400,13 +385,13 @@ const stages = [
   border-radius: 50%;
 }
 .light.red {
-  background: #ff5f56;
+  background: var(--vp-c-red-1, #ef4444);
 }
 .light.yellow {
-  background: #ffbd2e;
+  background: var(--vp-c-yellow-1, #f59e0b);
 }
 .light.green {
-  background: #27c93f;
+  background: var(--vp-c-green-1, #22c55e);
 }
 
 .window-title {
@@ -432,30 +417,30 @@ const stages = [
 /* Visualizations */
 /* Symbolism */
 .logic-gate {
-  border: 2px solid #334155;
+  border: 2px solid var(--vp-c-divider);
   padding: 1rem;
   border-radius: 8px;
   text-align: center;
-  background: white;
+  background: var(--vp-c-bg);
 }
 .input-group {
   display: flex;
   gap: 1rem;
   justify-content: center;
   margin-bottom: 0.5rem;
-  font-family: monospace;
+  font-family: var(--vp-font-family-mono);
 }
 .gate-box {
-  background: #334155;
-  color: white;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
   padding: 4px 10px;
   margin: 0.5rem 0;
   border-radius: 4px;
 }
 .math-note {
   margin-top: 1rem;
-  font-family: monospace;
-  color: #64748b;
+  font-family: var(--vp-font-family-mono);
+  color: var(--vp-c-text-2);
   font-size: 0.8rem;
 }
 
@@ -467,15 +452,16 @@ const stages = [
   gap: 1rem;
 }
 .tree-node {
-  border: 1px solid #cbd5e1;
+  border: 1px solid var(--vp-c-divider);
   padding: 6px 12px;
   border-radius: 20px;
-  background: white;
+  background: var(--vp-c-bg);
   font-size: 0.8rem;
+  color: var(--vp-c-text-1);
 }
 .tree-node.root {
-  border-color: #3b82f6;
-  color: #3b82f6;
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-brand);
   font-weight: bold;
 }
 .branches {
@@ -490,15 +476,15 @@ const stages = [
 }
 .condition {
   font-size: 0.7rem;
-  color: #64748b;
-  background: #f1f5f9;
+  color: var(--vp-c-text-2);
+  background: var(--vp-c-bg-alt);
   padding: 2px 6px;
   border-radius: 4px;
 }
 .kb-note {
   margin-top: 1rem;
   font-size: 0.8rem;
-  color: #64748b;
+  color: var(--vp-c-text-2);
   font-style: italic;
 }
 
@@ -518,17 +504,17 @@ const stages = [
   width: 12px;
   height: 12px;
   border-radius: 50%;
-  background: #cbd5e1;
-  border: 1px solid #94a3b8;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
 }
 .layer.input .neuron {
-  background: #93c5fd;
+  background: rgba(var(--vp-c-brand-rgb), 0.25);
 }
 .layer.hidden .neuron {
-  background: #fca5a5;
+  background: rgba(var(--vp-c-brand-rgb), 0.18);
 }
 .layer.output .neuron {
-  background: #86efac;
+  background: rgba(var(--vp-c-brand-rgb), 0.12);
 }
 .connections {
   position: absolute;
@@ -540,13 +526,13 @@ const stages = [
   opacity: 0.2;
 }
 .connections line {
-  stroke: #000;
+  stroke: var(--vp-c-text-2);
   stroke-width: 1;
 }
 .dl-note {
   margin-top: 2rem;
   font-size: 0.8rem;
-  color: #64748b;
+  color: var(--vp-c-text-2);
 }
 
 /* GenAI */
@@ -558,16 +544,16 @@ const stages = [
   width: 100%;
 }
 .transformer-block {
-  border: 2px solid #8b5cf6;
+  border: 2px solid var(--vp-c-brand);
   border-radius: 8px;
   padding: 0.5rem;
   width: 120px;
   text-align: center;
-  background: #f5f3ff;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
 }
 .block-layer {
-  border: 1px solid #ddd6fe;
-  background: white;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
   margin: 4px 0;
   padding: 4px;
   font-size: 0.7rem;
@@ -575,10 +561,10 @@ const stages = [
 }
 .chat-sim {
   width: 100%;
-  border: 1px solid #e2e8f0;
+  border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
   padding: 1rem;
-  background: white;
+  background: var(--vp-c-bg);
   font-size: 0.8rem;
 }
 .msg {
@@ -588,14 +574,14 @@ const stages = [
   max-width: 80%;
 }
 .msg.user {
-  background: #eff6ff;
+  background: rgba(var(--vp-c-brand-rgb), 0.1);
   margin-left: auto;
-  color: #1e40af;
+  color: var(--vp-c-text-1);
 }
 .msg.ai {
-  background: #f0fdf4;
+  background: var(--vp-c-bg-soft);
   margin-right: auto;
-  color: #166534;
+  color: var(--vp-c-text-1);
 }
 
 /* Impact Card */
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/AttentionMechanismDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/AttentionMechanismDemo.vue
new file mode 100644
index 0000000..8de8e49
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/AttentionMechanismDemo.vue
@@ -0,0 +1,251 @@
+<template>
+  <div class="attention-mechanism-demo">
+    <div class="demo-header">
+      <h4>👁️ 注意力机制演示</h4>
+      <p>点击词语，观察它如何"关注"句子中的其他词</p>
+    </div>
+
+    <div class="sentence-container">
+      <div class="sentence">
+        <span
+          v-for="(word, index) in sentence"
+          :key="index"
+          :class="['word-token', { active: activeIndex === index, source: activeIndex === index }]"
+          @click="selectWord(index)"
+        >
+          {{ word }}
+        </span>
+      </div>
+
+      <div class="attention-heatmap">
+        <transition-group name="fade">
+          <div
+            v-for="(attention, index) in attentionWeights"
+            :key="index"
+            v-show="activeIndex !== null"
+            :class="['attention-bar', { highlight: attention.weight > 0.5 }]"
+            :style="{ width: (attention.weight * 100) + '%', opacity: activeIndex !== null ? 1 : 0 }"
+          >
+            <span class="attention-label">{{ attention.word }}: {{ (attention.weight * 100).toFixed(0) }}%</span>
+          </div>
+        </transition-group>
+      </div>
+    </div>
+
+    <div class="explanation-panel">
+      <div v-if="activeIndex !== null" class="explanation-content">
+        <h5>当前词: "{{ sentence[activeIndex] }}"</h5>
+        <p><strong>注意力权重:</strong></p>
+        <ul>
+          <li v-for="(item, index) in attentionWeights" :key="index">
+            "{{ item.word }}" - {{ (item.weight * 100).toFixed(0) }}% 的关注度
+          </li>
+        </ul>
+        <p class="insight">
+          💡 <strong>关键洞察:</strong> {{ getInsight(activeIndex) }}
+        </p>
+      </div>
+      <div v-else class="placeholder">
+        👆 点击句子中的任意词语开始
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const sentence = ref(['小明', '把', '苹果', '给了', '他', '的', '母亲'])
+const activeIndex = ref(null)
+
+// 注意力权重矩阵（模拟）
+const attentionMatrix = {
+  0: [0.15, 0.05, 0.60, 0.05, 0.05, 0.05, 0.05], // 小明 主要关注 苹果、他
+  1: [0.10, 0.10, 0.40, 0.30, 0.05, 0.03, 0.02], // 把 主要关注 苹果、给了
+  2: [0.50, 0.10, 0.15, 0.15, 0.05, 0.03, 0.02], // 苹果 主要关注 小明
+  3: [0.10, 0.10, 0.35, 0.15, 0.20, 0.05, 0.05], // 给了 主要关注 苹果、他
+  4: [0.65, 0.05, 0.10, 0.10, 0.05, 0.03, 0.02], // 他 主要关注 小明
+  5: [0.08, 0.05, 0.07, 0.08, 0.62, 0.05, 0.05], // 的 主要关注 他
+  6: [0.25, 0.10, 0.15, 0.15, 0.20, 0.10, 0.05]  // 母亲 关注多个词
+}
+
+const insights = {
+  0: '当模型处理"小明"时，它最关注"苹果"（60%），因为这表明是"谁"拥有苹果。',
+  1: '"把"是介词，模型关注"苹果"和"给了"，理解动作的对象和方向。',
+  2: '"苹果"作为宾语，主要关注主语"小明"，确定归属关系。',
+  3: '"给了"关注"苹果"和"他"，理解传递动作的对象。',
+  4: '"他"最关注"小明"（65%），因为"他"指代的就是"小明"！',
+  5: '"的"连接"他"和"母亲"，主要关注"他"（62%）。',
+  6: '"母亲"作为句末宾语，关注前面的多个词语来理解完整语境。'
+}
+
+const attentionWeights = computed(() => {
+  if (activeIndex.value === null) return []
+
+  return sentence.value.map((word, index) => ({
+    word,
+    weight: attentionMatrix[activeIndex.value][index]
+  }))
+})
+
+const selectWord = (index) => {
+  activeIndex.value = index
+}
+
+const getInsight = (index) => {
+  return insights[index] || '模型正在理解这个词的上下文关系。'
+}
+</script>
+
+<style scoped>
+.attention-mechanism-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 1.5rem;
+}
+
+.demo-header h4 {
+  margin: 0 0 0.5rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.5rem;
+}
+
+.demo-header p {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.sentence-container {
+  background: var(--vp-c-bg);
+  padding: 2rem;
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  margin-bottom: 1.5rem;
+}
+
+.sentence {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: center;
+  margin-bottom: 2rem;
+}
+
+.word-token {
+  padding: 0.5rem 1rem;
+  background: var(--vp-c-bg-alt);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+  user-select: none;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.word-token:hover {
+  border-color: var(--vp-c-brand);
+}
+
+.word-token.active {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.attention-heatmap {
+  min-height: 150px;
+}
+
+.attention-bar {
+  margin-bottom: 0.75rem;
+  padding: 0.5rem 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.2);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.25);
+  border-radius: 4px;
+  color: var(--vp-c-text-1);
+  font-size: 0.875rem;
+  font-weight: 600;
+  transition: all 0.5s ease;
+}
+
+.attention-bar.highlight {
+  background: rgba(var(--vp-c-brand-rgb), 0.35);
+  border-color: rgba(var(--vp-c-brand-rgb), 0.4);
+}
+
+.attention-label {
+  white-space: nowrap;
+}
+
+.explanation-panel {
+  background: var(--vp-c-bg);
+  padding: 1.5rem;
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.explanation-content h5 {
+  margin: 0 0 1rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.25rem;
+}
+
+.explanation-content p {
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.6;
+}
+
+.explanation-content ul {
+  list-style: none;
+  padding: 0;
+  margin: 0 0 1rem 0;
+}
+
+.explanation-content li {
+  padding: 0.5rem;
+  background: var(--vp-c-bg-soft);
+  margin-bottom: 0.5rem;
+  border-radius: 4px;
+  border-left: 3px solid var(--vp-c-brand);
+  font-size: 0.875rem;
+  color: var(--vp-c-text-1);
+}
+
+.insight {
+  padding: 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.15);
+  border-radius: 6px;
+  color: var(--vp-c-text-1);
+  line-height: 1.6;
+}
+
+.placeholder {
+  text-align: center;
+  padding: 2rem;
+  color: var(--vp-c-text-2);
+  font-size: 1.125rem;
+}
+
+.fade-enter-active,
+.fade-leave-active {
+  transition: all 0.5s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+  transform: translateX(-20px);
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/BackpropagationDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/BackpropagationDemo.vue
new file mode 100644
index 0000000..bf53f3c
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/BackpropagationDemo.vue
@@ -0,0 +1,383 @@
+<template>
+  <div class="backpropagation-demo">
+    <div class="demo-header">
+      <h4>🔄 反向传播演示</h4>
+      <p>观察神经网络如何通过误差反向调整权重</p>
+    </div>
+
+    <div class="demo-content">
+      <div class="network-view">
+        <svg class="network-svg" viewBox="0 0 600 300">
+          <!-- Layers visualization -->
+          <g v-for="(layer, lIndex) in 3" :key="lIndex">
+            <text :x="100 + lIndex * 200" y="20" text-anchor="middle" class="layer-label">
+              {{ lIndex === 0 ? '输入层' : lIndex === 1 ? '隐藏层' : '输出层' }}
+            </text>
+
+            <circle
+              v-for="n in 3"
+              :key="`${lIndex}-${n}`"
+              :cx="100 + lIndex * 200"
+              :cy="60 + n * 70"
+              :r="25"
+              :class="['neuron', getNeuronClass(lIndex, n)]"
+            />
+          </g>
+
+          <!-- Connections with error flow -->
+          <line
+            v-for="conn in connections"
+            :key="conn.id"
+            :x1="conn.x1"
+            :y1="conn.y1"
+            :x2="conn.x2"
+            :y2="conn.y2"
+            :stroke="conn.color"
+            :stroke-width="conn.width"
+            :opacity="conn.opacity"
+            class="connection"
+          />
+        </svg>
+      </div>
+
+      <div class="controls-panel">
+        <div class="step-indicator">
+          <div
+            v-for="(step, index) in steps"
+            :key="index"
+            :class="['step', { active: currentStep === index, completed: currentStep > index }]"
+          >
+            <div class="step-number">{{ index + 1 }}</div>
+            <div class="step-label">{{ step }}</div>
+          </div>
+        </div>
+
+        <div class="error-display">
+          <div class="error-value">
+            误差: {{ errorValue.toFixed(4) }}
+          </div>
+          <div class="error-bar">
+            <div class="error-fill" :style="{ width: (errorValue * 100) + '%' }"></div>
+          </div>
+        </div>
+
+        <button @click="nextStep" class="step-btn" :disabled="currentStep >= 4">
+          {{ currentStep < 4 ? '下一步 ▶' : '完成 ✓' }}
+        </button>
+
+        <button @click="resetDemo" class="reset-btn">
+          🔄 重置演示
+        </button>
+
+        <div class="explanation">
+          <p><strong>当前步骤:</strong> {{ explanations[currentStep] }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const currentStep = ref(0)
+const errorValue = ref(0.95)
+const steps = ['前向传播', '计算误差', '反向传播', '更新权重']
+const explanations = [
+  '输入数据通过各层传递，得到预测输出',
+  '对比预测值和真实值，计算误差',
+  '将误差从输出层反向传递到各层',
+  '根据误差梯度调整每个神经元的权重'
+]
+
+const connections = ref([])
+
+// 初始化连接
+const initConnections = () => {
+  const conns = []
+  for (let l = 0; l < 2; l++) {
+    for (let i = 1; i <= 3; i++) {
+      for (let j = 1; j <= 3; j++) {
+        conns.push({
+          id: `${l}-${i}-${j}`,
+          x1: 100 + l * 200,
+          y1: 60 + i * 70,
+          x2: 100 + (l + 1) * 200,
+          y2: 60 + j * 70,
+          color: 'var(--vp-c-divider)',
+          width: 1,
+          opacity: 0.3,
+          active: false
+        })
+      }
+    }
+  }
+  connections.value = conns
+}
+
+const getNeuronClass = (layer, neuron) => {
+  if (currentStep.value === 0 && layer === 0) return 'active'
+  if (currentStep.value === 1 && layer === 2) return 'error'
+  if (currentStep.value >= 2) return 'updated'
+  return ''
+}
+
+const nextStep = () => {
+  if (currentStep.value < 4) {
+    currentStep.value++
+
+    // 模拟误差减小
+    if (currentStep.value === 2) {
+      errorValue.value = 0.95
+    } else if (currentStep.value === 3) {
+      errorValue.value = 0.65
+    } else if (currentStep.value === 4) {
+      errorValue.value = 0.32
+    }
+
+    // 更新连接显示
+    updateConnections()
+  }
+}
+
+const updateConnections = () => {
+  if (currentStep.value >= 2) {
+    connections.value.forEach((conn) => {
+      conn.color = 'var(--vp-c-brand)'
+      conn.width = 2
+      conn.opacity = 0.6
+    })
+  }
+}
+
+const resetDemo = () => {
+  currentStep.value = 0
+  errorValue.value = 0.95
+  initConnections()
+}
+
+// 初始化
+initConnections()
+</script>
+
+<style scoped>
+.backpropagation-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 1.5rem;
+}
+
+.demo-header h4 {
+  margin: 0 0 0.5rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.5rem;
+}
+
+.demo-header p {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.demo-content {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+}
+
+.network-view {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  padding: 1rem;
+  border-radius: 8px;
+}
+
+.network-svg {
+  width: 100%;
+  height: auto;
+}
+
+.layer-label {
+  font-size: 12px;
+  font-weight: 600;
+  fill: var(--vp-c-text-2);
+}
+
+.neuron {
+  fill: var(--vp-c-bg-alt);
+  stroke: var(--vp-c-divider);
+  stroke-width: 2;
+  transition: all 0.5s ease;
+}
+
+.neuron.active {
+  fill: var(--vp-c-green-1, #22c55e);
+  stroke: var(--vp-c-green-2, #16a34a);
+}
+
+.neuron.error {
+  fill: var(--vp-c-red-1, #ef4444);
+  stroke: var(--vp-c-red-2, #dc2626);
+}
+
+.neuron.updated {
+  fill: var(--vp-c-brand);
+  stroke: var(--vp-c-brand);
+}
+
+.connection {
+  transition: all 0.5s ease;
+}
+
+.controls-panel {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  padding: 1.5rem;
+  border-radius: 8px;
+}
+
+.step-indicator {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 1.5rem;
+}
+
+.step {
+  flex: 1;
+  text-align: center;
+  position: relative;
+  opacity: 0.4;
+  transition: all 0.3s ease;
+}
+
+.step.active,
+.step.completed {
+  opacity: 1;
+}
+
+.step-number {
+  width: 36px;
+  height: 36px;
+  margin: 0 auto 0.5rem;
+  background: var(--vp-c-bg-alt);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+  transition: all 0.3s ease;
+}
+
+.step.active .step-number {
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.step.completed .step-number {
+  background: var(--vp-c-green-1, #22c55e);
+  color: var(--vp-c-bg);
+}
+
+.step-label {
+  font-size: 0.75rem;
+  color: var(--vp-c-text-2);
+}
+
+.error-display {
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+}
+
+.error-value {
+  font-weight: 700;
+  color: var(--vp-c-red-1, #ef4444);
+  margin-bottom: 0.5rem;
+}
+
+.error-bar {
+  height: 8px;
+  background: var(--vp-c-bg-alt);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.error-fill {
+  height: 100%;
+  background: var(--vp-c-red-1, #ef4444);
+  transition: width 0.5s ease;
+}
+
+.step-btn,
+.reset-btn {
+  width: 100%;
+  padding: 0.75rem;
+  margin-bottom: 0.75rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.step-btn {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.step-btn:hover:not(:disabled) {
+  opacity: 0.95;
+}
+
+.step-btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.reset-btn {
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+.reset-btn:hover {
+  border-color: var(--vp-c-brand);
+}
+
+.explanation {
+  padding: 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border-left: 4px solid var(--vp-c-brand);
+  border-radius: 4px;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.15);
+}
+
+.explanation p {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+}
+
+.explanation strong {
+  color: var(--vp-c-text-1);
+}
+
+@media (max-width: 768px) {
+  .demo-content {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/CombinatorialExplosionDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/CombinatorialExplosionDemo.vue
new file mode 100644
index 0000000..9a0ad09
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/CombinatorialExplosionDemo.vue
@@ -0,0 +1,760 @@
+<template>
+  <div class="combinatorial-explosion-demo">
+    <div class="demo-container">
+      <div class="controls-panel">
+        <h4>🎯 组合爆炸模拟器</h4>
+        <p class="subtitle">亲手体验"规则指数增长"的恐怖</p>
+
+        <div class="control-group">
+          <label>
+            <span class="label-icon">🎨</span>
+            物体特征数量：{{ featureCount }}
+          </label>
+          <input
+            v-model.number="featureCount"
+            type="range"
+            min="2"
+            max="6"
+            step="1"
+            class="feature-slider"
+          />
+          <div class="feature-preview">
+            <span
+              v-for="i in featureCount"
+              :key="i"
+              class="feature-tag"
+              :style="{ background: getFeatureColor(i) }"
+            >
+              特征{{ i }}
+            </span>
+          </div>
+        </div>
+
+        <div class="control-group">
+          <label>
+            <span class="label-icon">🔢</span>
+            每个特征的可能值：{{ valuesPerFeature }}
+          </label>
+          <input
+            v-model.number="valuesPerFeature"
+            type="range"
+            min="2"
+            max="4"
+            step="1"
+            class="value-slider"
+          />
+        </div>
+
+        <div class="action-buttons">
+          <button @click="addRule" class="add-rule-btn" :disabled="ruleCount >= maxRules">
+            ✨ 添加规则 ({{ ruleCount }}/{{ maxRules }})
+          </button>
+          <button @click="autoGenerate" class="auto-btn" :disabled="autoGenerating">
+            ⚡ 自动生成
+          </button>
+          <button @click="resetRules" class="reset-btn">
+            🔄 重置
+          </button>
+        </div>
+      </div>
+
+      <div class="visualization-panel">
+        <div class="counter-display">
+          <div class="counter-label">需要的规则总数</div>
+          <transition name="count-update" mode="out-in">
+            <div :key="totalRules" class="counter-value">{{ formatNumber(totalRules) }}</div>
+          </transition>
+          <div class="counter-formula">
+            = {{ valuesPerFeature }}<sup>{{ featureCount }}</sup> =
+            <span class="highlight">{{ totalRules }}</span>
+          </div>
+          <div class="complexity-badge" :class="getComplexityLevel(totalRules)">
+            {{ getComplexityLabel(totalRules) }}
+          </div>
+        </div>
+
+        <div class="rules-container">
+          <transition-group name="rule-pop" tag="div" class="rules-grid">
+            <div
+              v-for="(rule, index) in displayedRules"
+              :key="rule.id"
+              class="rule-card"
+              :style="{ borderColor: rule.color }"
+            >
+              <div class="rule-number">#{{ index + 1 }}</div>
+              <div class="rule-content">
+                <code>{{ rule.text }}</code>
+              </div>
+              <div class="rule-visual" :style="{ background: rule.gradient }"></div>
+            </div>
+          </transition-group>
+        </div>
+
+        <transition name="warning-fade">
+          <div v-if="showWarning" class="warning-message">
+            <div class="warning-icon">💥</div>
+            <div class="warning-content">
+              <h5>组合爆炸！</h5>
+              <p>
+                即使只有 <strong>{{ featureCount }}</strong> 个特征，每个特征
+                <strong>{{ valuesPerFeature }}</strong> 种可能，也需要
+                <strong>{{ formatNumber(totalRules) }}</strong> 条规则！
+              </p>
+              <p>
+                这就是为什么<strong>基于规则的 AI</strong> 无法处理复杂现实——
+                规则数量呈<strong>指数级增长</strong>，根本写不完！
+              </p>
+            </div>
+          </div>
+        </transition>
+      </div>
+    </div>
+
+    <div class="comparison-box">
+      <h5>📊 对比：人类 vs 规则系统</h5>
+      <div class="comparison-grid">
+        <div class="comparison-item">
+          <div class="comparison-icon">🧠</div>
+          <div class="comparison-text">
+            <strong>人类识别猫</strong>
+            <p>看到 → 瞬间识别（无需列举规则）</p>
+          </div>
+        </div>
+        <div class="comparison-arrow">→</div>
+        <div class="comparison-item">
+          <div class="comparison-icon">🤖</div>
+          <div class="comparison-text">
+            <strong>规则系统识别猫</strong>
+            <p>需要 {{ formatNumber(totalRules) }} 条规则</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="insight-box">
+      <h5>💡 关键洞察</h5>
+      <p>
+        <strong>符号主义 AI 的致命弱点</strong>：现实世界的特征组合是无限的。
+        即使是简单的"识别猫"，也需要考虑：
+      </p>
+      <ul class="feature-list">
+        <li>形状：圆脸、尖脸...</li>
+        <li>耳朵：立耳、折耳...</li>
+        <li>毛色：黑、白、橘、花纹...</li>
+        <li>体型：胖、瘦、中等...</li>
+        <li>姿态：站立、趴下、跳跃...</li>
+        <li>...</li>
+      </ul>
+      <p class="conclusion">
+        <strong>结论</strong>：规则永远写不完，这就是为什么我们需要<strong>机器学习</strong>！
+      </p>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed, watch } from 'vue'
+
+const featureCount = ref(3)
+const valuesPerFeature = ref(3)
+const ruleCount = ref(0)
+const ruleIdCounter = ref(0)
+const autoGenerating = ref(false)
+const displayedRules = ref([])
+const maxRules = 20
+
+// Use theme colors (works for dark/light) instead of hardcoded hex.
+const featureColors = [
+  'rgba(var(--vp-c-brand-rgb), 0.18)',
+  'rgba(var(--vp-c-brand-rgb), 0.24)',
+  'rgba(var(--vp-c-brand-rgb), 0.3)',
+  'rgba(var(--vp-c-brand-rgb), 0.36)',
+  'rgba(var(--vp-c-brand-rgb), 0.42)',
+  'rgba(var(--vp-c-brand-rgb), 0.48)'
+]
+
+const totalRules = computed(() => {
+  return Math.pow(valuesPerFeature.value, featureCount.value)
+})
+
+const showWarning = computed(() => {
+  return ruleCount.value >= maxRules || totalRules.value > 50
+})
+
+const getFeatureColor = (index) => {
+  return featureColors[(index - 1) % featureColors.length]
+}
+
+const features = computed(() => {
+  const featureNames = ['形状', '颜色', '大小', '纹理', '尾巴', '耳朵']
+  return featureNames.slice(0, featureCount.value)
+})
+
+const valueOptions = computed(() => {
+  const options = {
+    2: ['小', '大'],
+    3: ['小', '中', '大'],
+    4: ['很小', '小', '大', '很大']
+  }
+  return options[valuesPerFeature.value] || options[3]
+})
+
+const generateRuleText = () => {
+  const conditions = features.value.map((feature, index) => {
+    const value = valueOptions.value[Math.floor(Math.random() * valuesPerFeature.value)]
+    return `${feature}=${value}`
+  })
+  return `IF ${conditions.join(' AND ')} THEN ...`
+}
+
+const generateColor = () => {
+  // Keep visuals subtle and theme-consistent; avoid heavy gradients.
+  return 'rgba(var(--vp-c-brand-rgb), 0.12)'
+}
+
+const addRule = () => {
+  if (ruleCount.value < maxRules) {
+    displayedRules.value.push({
+      id: ruleIdCounter.value++,
+      text: generateRuleText(),
+      color: getFeatureColor(Math.floor(Math.random() * featureCount.value) + 1),
+      gradient: generateColor()
+    })
+    ruleCount.value++
+  }
+}
+
+const autoGenerate = async () => {
+  if (autoGenerating.value) return
+
+  autoGenerating.value = true
+  const interval = setInterval(() => {
+    if (ruleCount.value >= maxRules) {
+      clearInterval(interval)
+      autoGenerating.value = false
+    } else {
+      addRule()
+    }
+  }, 100)
+}
+
+const resetRules = () => {
+  displayedRules.value = []
+  ruleCount.value = 0
+  autoGenerating.value = false
+}
+
+const formatNumber = (num) => {
+  if (num >= 1000000) return (num / 1000000).toFixed(1) + 'M'
+  if (num >= 1000) return (num / 1000).toFixed(1) + 'K'
+  return num.toString()
+}
+
+const getComplexityLevel = (num) => {
+  if (num < 10) return 'low'
+  if (num < 100) return 'medium'
+  if (num < 1000) return 'high'
+  return 'extreme'
+}
+
+const getComplexityLabel = (num) => {
+  if (num < 10) return '😊 简单'
+  if (num < 100) return '😐 复杂'
+  if (num < 1000) return '😰 非常复杂'
+  return '😱 指数爆炸'
+}
+
+// 重置规则当特征数变化时
+watch([featureCount, valuesPerFeature], () => {
+  resetRules()
+})
+</script>
+
+<style scoped>
+.combinatorial-explosion-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-container {
+  display: grid;
+  grid-template-columns: 1fr 1.2fr;
+  gap: 2rem;
+  margin-bottom: 2rem;
+}
+
+.controls-panel {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  padding: 1.5rem;
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+}
+
+.controls-panel h4 {
+  margin: 0 0 0.5rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.5rem;
+}
+
+.subtitle {
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+  margin-bottom: 1.5rem;
+}
+
+.control-group {
+  margin-bottom: 1.5rem;
+}
+
+.control-group label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 600;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
+}
+
+.label-icon {
+  font-size: 1.25rem;
+}
+
+.feature-slider,
+.value-slider {
+  width: 100%;
+  height: 6px;
+  border-radius: 3px;
+  background: var(--vp-c-divider);
+  outline: none;
+  margin-bottom: 0.75rem;
+}
+
+.feature-slider::-webkit-slider-thumb,
+.value-slider::-webkit-slider-thumb {
+  appearance: none;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: var(--vp-c-brand);
+  cursor: pointer;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.25);
+}
+
+.feature-preview {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.feature-tag {
+  padding: 0.35rem 0.75rem;
+  color: var(--vp-c-bg);
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  background: var(--vp-c-brand);
+}
+
+.action-buttons {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.add-rule-btn,
+.auto-btn,
+.reset-btn {
+  width: 100%;
+  padding: 0.875rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  font-weight: 600;
+  font-size: 1rem;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.add-rule-btn {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.add-rule-btn:hover:not(:disabled) {
+  opacity: 0.95;
+}
+
+.add-rule-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.auto-btn {
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+.auto-btn:hover:not(:disabled) {
+  border-color: var(--vp-c-brand);
+}
+
+.reset-btn {
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-2);
+}
+
+.reset-btn:hover {
+  border-color: var(--vp-c-brand);
+}
+
+.visualization-panel {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  padding: 1.5rem;
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+}
+
+.counter-display {
+  text-align: center;
+  padding: 2rem 1.5rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.15);
+  color: var(--vp-c-text-1);
+  border-radius: 12px;
+  margin-bottom: 1.5rem;
+  position: relative;
+  overflow: hidden;
+}
+
+.counter-display::before {
+  content: '';
+  position: absolute;
+  top: -50%;
+  left: -50%;
+  width: 200%;
+  height: 200%;
+  background: radial-gradient(
+    circle,
+    rgba(var(--vp-c-brand-rgb), 0.08) 0%,
+    transparent 70%
+  );
+  animation: pulse 3s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { transform: scale(1); opacity: 0.5; }
+  50% { transform: scale(1.1); opacity: 0.8; }
+}
+
+.counter-label {
+  font-size: 0.875rem;
+  opacity: 0.9;
+  margin-bottom: 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.counter-value {
+  font-size: 3.5rem;
+  font-weight: 800;
+  line-height: 1;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-brand);
+}
+
+.counter-formula {
+  font-size: 1rem;
+  margin-bottom: 1rem;
+  font-family: var(--vp-font-family-mono);
+  color: var(--vp-c-text-2);
+}
+
+.counter-formula .highlight {
+  color: var(--vp-c-brand);
+  font-weight: 700;
+  font-size: 1.2rem;
+}
+
+.complexity-badge {
+  display: inline-block;
+  padding: 0.5rem 1.25rem;
+  border-radius: 25px;
+  font-weight: 700;
+  font-size: 0.875rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+}
+
+.complexity-badge.low {
+  border-color: var(--vp-c-green-1, #22c55e);
+}
+
+.complexity-badge.medium {
+  border-color: var(--vp-c-yellow-1, #f59e0b);
+}
+
+.complexity-badge.high {
+  border-color: var(--vp-c-yellow-1, #f59e0b);
+}
+
+.complexity-badge.extreme {
+  border-color: var(--vp-c-red-1, #ef4444);
+  animation: shake 0.5s ease-in-out;
+}
+
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-5px); }
+  75% { transform: translateX(5px); }
+}
+
+.rules-container {
+  min-height: 300px;
+  max-height: 400px;
+  overflow-y: auto;
+  padding: 0.5rem;
+}
+
+.rules-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 0.75rem;
+}
+
+.rule-card {
+  position: relative;
+  padding: 0.75rem;
+  background: var(--vp-c-bg);
+  border-left: 4px solid var(--vp-c-brand);
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  overflow: hidden;
+}
+
+.rule-number {
+  font-size: 0.65rem;
+  font-weight: 700;
+  color: var(--vp-c-brand);
+  margin-bottom: 0.35rem;
+  text-transform: uppercase;
+}
+
+.rule-content code {
+  display: block;
+  color: var(--vp-c-text-1);
+  font-size: 0.7rem;
+  line-height: 1.4;
+  word-break: break-word;
+  font-family: var(--vp-font-family-mono);
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  padding: 0.35rem;
+  border-radius: 3px;
+}
+
+.rule-visual {
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: 40px;
+  height: 40px;
+  opacity: 0.3;
+  border-radius: 0 6px 0 6px;
+}
+
+.warning-message {
+  display: flex;
+  gap: 1rem;
+  margin-top: 1.5rem;
+  padding: 1.25rem 1.5rem;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-left: 4px solid var(--vp-c-yellow-1, #f59e0b);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.warning-icon {
+  font-size: 2.5rem;
+  flex-shrink: 0;
+  animation: bounce 1s ease-in-out infinite;
+}
+
+@keyframes bounce {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+
+.warning-content h5 {
+  margin: 0 0 0.75rem 0;
+  font-size: 1.25rem;
+}
+
+.warning-content p {
+  margin: 0 0 0.5rem 0;
+  line-height: 1.6;
+}
+
+.warning-content strong {
+  color: var(--vp-c-text-1);
+}
+
+.comparison-box {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  padding: 1.5rem;
+  margin-bottom: 1.5rem;
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+}
+
+.comparison-box h5 {
+  margin: 0 0 1.25rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.25rem;
+}
+
+.comparison-grid {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  gap: 1rem;
+  align-items: center;
+}
+
+.comparison-item {
+  display: flex;
+  gap: 1rem;
+  padding: 1rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+}
+
+.comparison-icon {
+  font-size: 2.5rem;
+  flex-shrink: 0;
+}
+
+.comparison-text strong {
+  display: block;
+  margin-bottom: 0.5rem;
+  color: var(--vp-c-text-1);
+}
+
+.comparison-text p {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+}
+
+.comparison-arrow {
+  font-size: 2rem;
+  color: var(--vp-c-text-3);
+}
+
+.insight-box {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  padding: 1.5rem;
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+}
+
+.insight-box h5 {
+  margin: 0 0 1rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.25rem;
+}
+
+.insight-box p {
+  margin: 0 0 1rem 0;
+  line-height: 1.8;
+}
+
+.insight-box .conclusion {
+  padding: 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border-left: 4px solid var(--vp-c-brand);
+  border-radius: 4px;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.15);
+}
+
+.feature-list {
+  list-style: none;
+  padding: 0;
+  margin: 1rem 0;
+}
+
+.feature-list li {
+  padding: 0.5rem 0.5rem 0.5rem 2rem;
+  position: relative;
+  color: var(--vp-c-text-2);
+}
+
+.feature-list li::before {
+  content: '✦';
+  position: absolute;
+  left: 0;
+  color: var(--vp-c-brand);
+  font-weight: 700;
+}
+
+/* Transitions */
+.count-update-enter-active,
+.count-update-leave-active {
+  transition: all 0.3s ease;
+}
+
+.count-update-enter-from {
+  opacity: 0;
+  transform: scale(0.5);
+}
+
+.count-update-leave-to {
+  opacity: 0;
+  transform: scale(1.5);
+}
+
+.rule-pop-enter-active {
+  transition: all 0.4s cubic-bezier(0.68, -0.55, 0.265, 1.55);
+}
+
+.rule-pop-enter-from {
+  opacity: 0;
+  transform: scale(0.3) rotate(-10deg);
+}
+
+.warning-fade-enter-active,
+.warning-fade-leave-active {
+  transition: all 0.5s ease;
+}
+
+.warning-fade-enter-from,
+.warning-fade-leave-to {
+  opacity: 0;
+  transform: translateY(-20px);
+}
+
+@media (max-width: 768px) {
+  .demo-container {
+    grid-template-columns: 1fr;
+  }
+  .comparison-grid {
+    grid-template-columns: 1fr;
+  }
+  .comparison-arrow {
+    transform: rotate(90deg);
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/DiscriminativeVsGenerativeDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/DiscriminativeVsGenerativeDemo.vue
new file mode 100644
index 0000000..2740f04
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/DiscriminativeVsGenerativeDemo.vue
@@ -0,0 +1,401 @@
+<template>
+  <div class="discriminative-vs-generative-demo">
+    <div class="demo-header">
+      <h4>🎯 判别式 vs 生成式 AI</h4>
+      <p>理解两种不同的 AI 范式</p>
+    </div>
+
+    <div class="comparison-container">
+      <!-- Discriminative AI -->
+      <div class="ai-panel discriminative" :class="{ active: mode === 'discriminative' }" @click="mode = 'discriminative'">
+        <div class="panel-header">
+          <div class="icon">🔍</div>
+          <h5>判别式 AI</h5>
+          <div class="tag">分类/识别</div>
+        </div>
+
+        <div class="panel-content">
+          <div class="input-output">
+            <div class="io-box input">
+              <div class="io-label">输入</div>
+              <div class="io-content">
+                <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='60' height='60' viewBox='0 0 60 60'%3E%3Crect width='60' height='60' fill='%2348bb78'/%3E%3Ctext x='30' y='35' text-anchor='middle' fill='white' font-size='12'%3E猫图%3C/text%3E%3C/svg%3E" alt="cat" />
+              </div>
+            </div>
+
+            <div class="arrow">↓</div>
+
+            <div class="io-box output">
+              <div class="io-label">输出</div>
+              <div class="io-content">
+                <div class="result-tag">这是猫</div>
+                <div class="probability">置信度: 98%</div>
+              </div>
+            </div>
+          </div>
+
+          <div class="examples">
+            <h6>典型应用:</h6>
+            <div class="example-tags">
+              <span class="tag">图像分类</span>
+              <span class="tag">垃圾邮件过滤</span>
+              <span class="tag">疾病诊断</span>
+              <span class="tag">人脸识别</span>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Generative AI -->
+      <div class="ai-panel generative" :class="{ active: mode === 'generative' }" @click="mode = 'generative'">
+        <div class="panel-header">
+          <div class="icon">✨</div>
+          <h5>生成式 AI</h5>
+          <div class="tag">创造/生成</div>
+        </div>
+
+        <div class="panel-content">
+          <div class="input-output">
+            <div class="io-box input">
+              <div class="io-label">输入</div>
+              <div class="io-content">
+                <div class="prompt-text">"一只戴墨镜的猫"</div>
+              </div>
+            </div>
+
+            <div class="arrow">↓</div>
+
+            <div class="io-box output">
+              <div class="io-label">输出</div>
+              <div class="io-content">
+                <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='60' viewBox='0 0 80 60'%3E%3Crect width='80' height='60' fill='%23667eea'/%3E%3Ccircle cx='30' cy='25' r='3' fill='black'/%3E%3Cline x1='27' y1='25' x2='33' y2='25' stroke='black' stroke-width='1'/%3E%3Cellipse cx='30' cy='30' rx='8' ry='6' fill='white'/%3E%3Ccircle cx='30' cy='28' r='2' fill='black'/%3E%3Cpath d='M 22 20 Q 30 15 38 20' stroke='orange' stroke-width='2' fill='none'/%3E%3Cpath d='M 38 35 Q 50 30 55 40' stroke='gray' stroke-width='3' fill='none'/%3E%3C/svg%3E" alt="generated cat" />
+                <div class="generated-label">生成图像 ✓</div>
+              </div>
+            </div>
+          </div>
+
+          <div class="examples">
+            <h6>典型应用:</h6>
+            <div class="example-tags">
+              <span class="tag">ChatGPT</span>
+              <span class="tag">Midjourney</span>
+              <span class="tag">代码生成</span>
+              <span class="tag">音乐创作</span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="comparison-table">
+      <h5>📊 核心差异对比</h5>
+      <table>
+        <thead>
+          <tr>
+            <th>维度</th>
+            <th>判别式 AI</th>
+            <th>生成式 AI</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><strong>目标</strong></td>
+            <td>区分、分类、识别</td>
+            <td>创造、生成新内容</td>
+          </tr>
+          <tr>
+            <td><strong>输入</strong></td>
+            <td>数据（图像、文本等）</td>
+            <td>提示词、噪声、种子</td>
+          </tr>
+          <tr>
+            <td><strong>输出</strong></td>
+            <td>标签、类别、概率</td>
+            <td>新的数据（文本、图像等）</td>
+          </tr>
+          <tr>
+            <td><strong>学习方式</strong></td>
+            <td>学习 P(标签|数据)</td>
+            <td>学习 P(数据)</td>
+          </tr>
+          <tr>
+            <td><strong>代表模型</strong></td>
+            <td>ResNet, BERT(分类)</td>
+            <td>GPT, DALL-E, Stable Diffusion</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="key-insight">
+      <h5>💡 关键洞察</h5>
+      <p>
+        <strong>判别式 AI</strong>就像考试中的"选择题"——从给定选项中选出正确答案。<br>
+        <strong>生成式 AI</strong>就像考试中的"简答题"——自己创造出全新的答案。
+      </p>
+      <p class="note">
+        从 2020 年代开始，生成式 AI 迅速崛起，成为人工智能的主流方向。
+        GPT、Midjourney 等模型展现出了惊人的创造力，开启了 AI 2.0 时代。
+      </p>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const mode = ref('discriminative')
+</script>
+
+<style scoped>
+.discriminative-vs-generative-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 2rem;
+}
+
+.demo-header h4 {
+  margin: 0 0 0.5rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.5rem;
+}
+
+.demo-header p {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.comparison-container {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+  margin-bottom: 2rem;
+}
+
+.ai-panel {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  padding: 1.5rem;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.ai-panel:hover {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+}
+
+.ai-panel.active {
+  border-color: var(--vp-c-brand);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.ai-panel.discriminative {
+  --ev-panel-accent: var(--vp-c-green-1, #22c55e);
+}
+
+.ai-panel.discriminative.active {
+  border-color: var(--ev-panel-accent);
+}
+
+.ai-panel.generative {
+  --ev-panel-accent: var(--vp-c-brand);
+}
+
+.ai-panel.generative.active {
+  border-color: var(--ev-panel-accent);
+}
+
+.panel-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 1.5rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.icon {
+  font-size: 2rem;
+}
+
+.panel-header h5 {
+  margin: 0;
+  flex: 1;
+  font-size: 1.25rem;
+  color: var(--vp-c-text-1);
+}
+
+.tag {
+  padding: 0.25rem 0.75rem;
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+}
+
+.input-output {
+  margin-bottom: 1.5rem;
+}
+
+.io-box {
+  margin-bottom: 1rem;
+}
+
+.io-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--vp-c-text-2);
+  margin-bottom: 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.io-content {
+  padding: 1rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  text-align: center;
+  min-height: 80px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.io-content img {
+  max-width: 100%;
+  height: auto;
+}
+
+.result-tag,
+.prompt-text {
+  font-weight: 600;
+  font-size: 1rem;
+  color: var(--vp-c-text-1);
+}
+
+.probability {
+  font-size: 0.875rem;
+  color: var(--vp-c-green-1, #22c55e);
+  font-weight: 600;
+}
+
+.generated-label {
+  font-size: 0.75rem;
+  color: var(--vp-c-brand);
+  font-weight: 600;
+}
+
+.arrow {
+  text-align: center;
+  font-size: 1.5rem;
+  color: var(--vp-c-text-3);
+  margin: 0.5rem 0;
+}
+
+.examples h6 {
+  margin: 0 0 0.75rem 0;
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+}
+
+.example-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.example-tags .tag {
+  padding: 0.25rem 0.75rem;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 15px;
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.comparison-table {
+  background: var(--vp-c-bg);
+  padding: 1.5rem;
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  margin-bottom: 1.5rem;
+}
+
+.comparison-table h5 {
+  margin: 0 0 1rem 0;
+  color: var(--vp-c-text-1);
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+thead th {
+  text-align: left;
+  padding: 0.75rem;
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-1);
+  font-weight: 600;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+tbody td {
+  padding: 0.75rem;
+  border-bottom: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+  line-height: 1.6;
+}
+
+tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.key-insight {
+  background: rgba(var(--vp-c-brand-rgb), 0.08);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.15);
+  padding: 1.5rem;
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.key-insight h5 {
+  margin: 0 0 1rem 0;
+  color: var(--vp-c-text-1);
+}
+
+.key-insight p {
+  margin: 0 0 1rem 0;
+  line-height: 1.8;
+}
+
+.key-insight .note {
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+  padding: 0.75rem;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 4px;
+}
+
+@media (max-width: 768px) {
+  .comparison-container {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/GPTEvolutionDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/GPTEvolutionDemo.vue
new file mode 100644
index 0000000..4a33b93
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/GPTEvolutionDemo.vue
@@ -0,0 +1,468 @@
+<template>
+  <div class="gpt-evolution-demo">
+    <div class="demo-header">
+      <h4>🚀 GPT 进化历程</h4>
+      <p>从 GPT-1 到 GPT-4 的演进之路</p>
+    </div>
+
+    <div class="timeline-container">
+      <div class="timeline-track"></div>
+
+      <div
+        v-for="(model, index) in gptModels"
+        :key="index"
+        class="timeline-item"
+        :class="{ active: activeModel === index }"
+        @click="selectModel(index)"
+      >
+        <div class="timeline-marker">
+          <div class="marker-dot"></div>
+        </div>
+        <div class="timeline-content">
+          <div class="model-year">{{ model.year }}</div>
+          <div class="model-name">{{ model.name }}</div>
+          <div class="model-stats">
+            <span class="stat">📊 {{ model.parameters }}</span>
+            <span class="stat">🎯 {{ model.context }}</span>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <transition name="fade-slide">
+      <div v-if="activeModel !== null" class="model-details">
+        <div class="details-header">
+          <h5>{{ gptModels[activeModel].name }}</h5>
+          <span class="year-badge">{{ gptModels[activeModel].year }}</span>
+        </div>
+
+        <div class="details-grid">
+          <div class="detail-card">
+            <div class="card-label">参数量</div>
+            <div class="card-value">{{ gptModels[activeModel].parameters }}</div>
+            <div class="card-note">{{ gptModels[activeModel].paramDetail }}</div>
+          </div>
+
+          <div class="detail-card">
+            <div class="card-label">上下文窗口</div>
+            <div class="card-value">{{ gptModels[activeModel].context }}</div>
+            <div class="card-note">{{ gptModels[activeModel].contextDetail }}</div>
+          </div>
+
+          <div class="detail-card">
+            <div class="card-label">主要能力</div>
+            <div class="card-value">{{ gptModels[activeModel].capability }}</div>
+          </div>
+        </div>
+
+        <div class="model-description">
+          <h6>📝 模型简介</h6>
+          <p>{{ gptModels[activeModel].description }}</p>
+        </div>
+
+        <div class="model-milestones">
+          <h6>🎯 关键里程碑</h6>
+          <ul>
+            <li v-for="(milestone, i) in gptModels[activeModel].milestones" :key="i">
+              {{ milestone }}
+            </li>
+          </ul>
+        </div>
+      </div>
+    </transition>
+
+    <div class="evolution-insight">
+      <h5>💡 进化趋势</h5>
+      <div class="trend-grid">
+        <div class="trend-item">
+          <div class="trend-icon">📈</div>
+          <div class="trend-text">参数量从 1.17 亿增长到万亿级别</div>
+        </div>
+        <div class="trend-item">
+          <div class="trend-icon">🧠</div>
+          <div class="trend-text">从文本生成到多模态（图像、音频、视频）</div>
+        </div>
+        <div class="trend-item">
+          <div class="trend-icon">🎯</div>
+          <div class="trend-text">上下文窗口从 512 tokens 扩展到 128k+</div>
+        </div>
+        <div class="trend-item">
+          <div class="trend-icon">🌐</div>
+          <div class="trend-text">从单语言到多语言，从通用到专业领域</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const activeModel = ref(0)
+
+const gptModels = ref([
+  {
+    name: 'GPT-1',
+    year: '2018',
+    parameters: '1.17 亿',
+    paramDetail: '117M',
+    context: '512 tokens',
+    contextDetail: '约 384 英文单词',
+    capability: '文本生成',
+    description: 'OpenAI 发布的首个 GPT 模型，证明了生成式预训练的可行性。它采用"预训练 + 微调"范式，在无标注文本上学习语言模式。',
+    milestones: [
+      '首次验证 Transformer 架构在语言模型中的有效性',
+      '引入生成式预训练方法',
+      '为后续 GPT 系列奠定基础'
+    ]
+  },
+  {
+    name: 'GPT-2',
+    year: '2019',
+    parameters: '15 亿',
+    paramDetail: '1.5B',
+    context: '1024 tokens',
+    contextDetail: '约 768 英文单词',
+    capability: '高质量文本生成',
+    description: 'GPT-2 的规模扩大了 13 倍，能够生成连贯、高质量的文本。由于担心滥用，OpenAI 最初只发布了缩小版本，引发广泛争议。',
+    milestones: [
+      '参数量突破 10 亿级别',
+      '展现出惊人的零样本学习能力',
+      "引发 AI 安全和滥用的讨论",
+      '最终完整版本于 2019 年 11 月发布'
+    ]
+  },
+  {
+    name: 'GPT-3',
+    year: '2020',
+    parameters: '1750 亿',
+    paramDetail: '175B',
+    context: '2048 tokens',
+    contextDetail: '约 1536 英文单词',
+    capability: '少样本学习',
+    description: 'GPT-3 是当时规模最大的语言模型，展现出强大的少样本和零样本学习能力。它证明了"规模就是一切"的假设，只需通过提示词就能完成各种任务。',
+    milestones: [
+      '参数量达到 1750 亿，比 GPT-2 增长 116 倍',
+      '少样本学习能力震惊学术界',
+      '催生了大量基于 API 的应用',
+      'OpenAI 开始提供商业 API 服务'
+    ]
+  },
+  {
+    name: 'GPT-3.5',
+    year: '2022',
+    parameters: '未知',
+    paramDetail: '估计 2000 亿+',
+    context: '4096 tokens',
+    contextDetail: '约 3072 英文单词',
+    capability: '对话系统',
+    description: 'GPT-3.5 在 GPT-3 基础上引入了对话训练和强化学习（RLHF），成为 ChatGPT 的基础模型。它能够进行自然、连贯的多轮对话，是 AI 历史上的重要里程碑。',
+    milestones: [
+      '引入人类反馈强化学习（RLHF）',
+      'ChatGPT 发布，5 天用户破百万',
+      '2 个月月活破亿，创历史记录',
+      '掀起全球 AI 热潮'
+    ]
+  },
+  {
+    name: 'GPT-4',
+    year: '2023',
+    parameters: '未知',
+    paramDetail: '估计 1.8 万亿',
+    context: '8192-32768 tokens',
+    contextDetail: '最多 50 页文档',
+    capability: '多模态智能',
+    description: 'GPT-4 是一个多模态大模型，能够处理文本、图像等多种输入。它在各项基准测试中接近人类水平，并在复杂推理、数学、编程等任务上表现出色。',
+    milestones: [
+      '首个大规模多模态模型',
+      '在律师考试、奥数等高难度测试中表现出色',
+      '支持更长上下文（最多 32k tokens）',
+      '推出 GPT-4 Turbo，速度更快、价格更低'
+    ]
+  }
+])
+
+const selectModel = (index) => {
+  activeModel.value = index
+}
+</script>
+
+<style scoped>
+.gpt-evolution-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 2rem;
+}
+
+.demo-header h4 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1.5rem;
+}
+
+.demo-header p {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.timeline-container {
+  position: relative;
+  padding: 1rem 0;
+  margin-bottom: 2rem;
+}
+
+.timeline-track {
+  position: absolute;
+  left: 20px;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  background: var(--vp-c-divider);
+  border-radius: 2px;
+}
+
+.timeline-item {
+  position: relative;
+  display: flex;
+  margin-bottom: 1.5rem;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.timeline-item:hover {
+  opacity: 0.9;
+}
+
+.timeline-item.active .marker-dot {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+}
+
+.timeline-marker {
+  width: 44px;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1;
+}
+
+.marker-dot {
+  width: 16px;
+  height: 16px;
+  background: var(--vp-c-bg);
+  border-radius: 50%;
+  border: 3px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+}
+
+.timeline-content {
+  margin-left: 1rem;
+  padding: 1rem 1.5rem;
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  flex: 1;
+}
+
+.timeline-item.active .timeline-content {
+  border-color: var(--vp-c-brand);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.model-year {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--vp-c-text-2);
+  margin-bottom: 0.25rem;
+}
+
+.model-name {
+  font-size: 1.25rem;
+  font-weight: 700;
+  margin-bottom: 0.5rem;
+}
+
+.model-stats {
+  display: flex;
+  gap: 1rem;
+  font-size: 0.75rem;
+  color: var(--vp-c-text-2);
+}
+
+.model-details {
+  margin-bottom: 2rem;
+  padding: 1.5rem;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.details-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1.5rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.details-header h5 {
+  margin: 0;
+  font-size: 1.5rem;
+  color: var(--vp-c-text-1);
+}
+
+.year-badge {
+  padding: 0.5rem 1rem;
+  background: rgba(var(--vp-c-brand-rgb), 0.12);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.2);
+  color: var(--vp-c-brand);
+  border-radius: 20px;
+  font-weight: 600;
+}
+
+.details-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.detail-card {
+  padding: 1rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  text-align: center;
+}
+
+.card-label {
+  font-size: 0.75rem;
+  color: var(--vp-c-text-2);
+  margin-bottom: 0.5rem;
+  text-transform: uppercase;
+}
+
+.card-value {
+  font-size: 1.25rem;
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.25rem;
+}
+
+.card-note {
+  font-size: 0.75rem;
+  color: var(--vp-c-text-2);
+}
+
+.model-description,
+.model-milestones {
+  margin-bottom: 1rem;
+}
+
+.model-description h6,
+.model-milestones h6 {
+  margin: 0 0 0.75rem 0;
+  color: var(--vp-c-text-1);
+}
+
+.model-description p {
+  margin: 0;
+  line-height: 1.8;
+  color: var(--vp-c-text-2);
+}
+
+.model-milestones ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.model-milestones li {
+  padding: 0.5rem 0.5rem 0.5rem 1.5rem;
+  position: relative;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+}
+
+.model-milestones li::before {
+  content: '✓';
+  position: absolute;
+  left: 0;
+  color: var(--vp-c-green-1, #22c55e);
+  font-weight: 700;
+}
+
+.evolution-insight {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  padding: 1.5rem;
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.evolution-insight h5 {
+  margin: 0 0 1rem 0;
+  color: var(--vp-c-text-1);
+}
+
+.trend-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1rem;
+}
+
+.trend-item {
+  display: flex;
+  gap: 0.75rem;
+  padding: 1rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+}
+
+.trend-icon {
+  font-size: 1.5rem;
+  flex-shrink: 0;
+}
+
+.trend-text {
+  font-size: 0.875rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.5;
+}
+
+.fade-slide-enter-active,
+.fade-slide-leave-active {
+  transition: all 0.3s ease;
+}
+
+.fade-slide-enter-from {
+  opacity: 0;
+  transform: translateX(20px);
+}
+
+.fade-slide-leave-to {
+  opacity: 0;
+  transform: translateX(-20px);
+}
+
+@media (max-width: 768px) {
+  .details-grid {
+    grid-template-columns: 1fr;
+  }
+  .trend-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/NeuralNetworkVisualizationDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/NeuralNetworkVisualizationDemo.vue
new file mode 100644
index 0000000..82cc697
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/ai-history/NeuralNetworkVisualizationDemo.vue
@@ -0,0 +1,390 @@
+<template>
+  <div class="neural-network-viz-demo">
+    <div class="demo-header">
+      <h4>🧠 神经网络可视化</h4>
+      <p>观察数据如何在神经网络中流动</p>
+    </div>
+
+    <div class="network-container">
+      <svg ref="svgRef" class="network-svg" :width="svgWidth" :height="svgHeight">
+        <defs>
+          <linearGradient id="connectionGradient" x1="0%" y1="0%" x2="100%" y2="0%">
+          <stop
+            offset="0%"
+            style="stop-color: var(--vp-c-brand); stop-opacity: 0.15"
+          />
+          <stop
+            offset="100%"
+            style="stop-color: var(--vp-c-brand); stop-opacity: 0.45"
+          />
+        </linearGradient>
+        </defs>
+
+        <!-- Connections -->
+        <g class="connections">
+          <line
+            v-for="conn in connections"
+            :key="conn.id"
+            :x1="conn.x1"
+            :y1="conn.y1"
+            :x2="conn.x2"
+            :y2="conn.y2"
+            :stroke-width="conn.width"
+            :opacity="conn.opacity"
+            stroke="url(#connectionGradient)"
+            class="connection-line"
+          />
+        </g>
+
+        <!-- Neurons -->
+        <g class="neurons">
+          <g
+            v-for="neuron in neurons"
+            :key="neuron.id"
+            :transform="`translate(${neuron.x}, ${neuron.y})`"
+            class="neuron-group"
+            :class="{ active: neuron.active, input: neuron.layer === 0, output: neuron.layer === layers.length - 1 }"
+          >
+            <circle
+              :r="neuron.radius"
+              class="neuron-circle"
+              @click="activateNeuron(neuron)"
+            />
+            <text
+              v-if="neuron.label"
+              y="30"
+              text-anchor="middle"
+              class="neuron-label"
+            >
+              {{ neuron.label }}
+            </text>
+          </g>
+        </g>
+      </svg>
+    </div>
+
+    <div class="layer-info">
+      <div
+        v-for="(layer, index) in layerConfigs"
+        :key="index"
+        class="layer-card"
+        :class="{ active: currentLayer === index }"
+        @click="currentLayer = index"
+      >
+        <div class="layer-badge">{{ layer.name }}</div>
+        <div class="layer-neurons">{{ layer.neurons }} 个神经元</div>
+        <div class="layer-desc">{{ layer.desc }}</div>
+      </div>
+    </div>
+
+    <div class="controls">
+      <button @click="startForwardPropagation" class="action-btn">
+        ▶️ 前向传播
+      </button>
+      <button @click="resetNetwork" class="action-btn secondary">
+        🔄 重置
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+
+const svgWidth = 800
+const svgHeight = 400
+const currentLayer = ref(0)
+const animationId = ref(null)
+
+const layers = ref([4, 6, 6, 3]) // 输入层、2个隐藏层、输出层
+const layerConfigs = ref([
+  { name: '输入层', neurons: 4, desc: '接收原始数据（如图片像素）' },
+  { name: '隐藏层 1', neurons: 6, desc: '识别边缘和简单特征' },
+  { name: '隐藏层 2', neurons: 6, desc: '识别形状和复杂特征' },
+  { name: '输出层', neurons: 3, desc: '输出分类结果' }
+])
+
+const neurons = ref([])
+const connections = ref([])
+
+// 计算神经元位置
+const calculateNeurons = () => {
+  neurons.value = []
+  const layerSpacing = svgWidth / (layers.value.length + 1)
+
+  layers.value.forEach((neuronCount, layerIndex) => {
+    const x = layerSpacing * (layerIndex + 1)
+    const neuronSpacing = svgHeight / (neuronCount + 1)
+
+    for (let i = 0; i < neuronCount; i++) {
+      const y = neuronSpacing * (i + 1)
+      neurons.value.push({
+        id: `${layerIndex}-${i}`,
+        layer: layerIndex,
+        x,
+        y,
+        radius: 20,
+        active: false,
+        label:
+          layerIndex === 0
+            ? ['像素1', '像素2', '像素3', '像素4'][i]
+            : layerIndex === layers.value.length - 1
+            ? ['猫', '狗', '鸟'][i]
+            : ''
+      })
+    }
+  })
+}
+
+// 计算连接
+const calculateConnections = () => {
+  connections.value = []
+  let connId = 0
+
+  for (let l = 0; l < layers.value.length - 1; l++) {
+    const currentLayerNeurons = neurons.value.filter((n) => n.layer === l)
+    const nextLayerNeurons = neurons.value.filter((n) => n.layer === l + 1)
+
+    currentLayerNeurons.forEach((fromNeuron) => {
+      nextLayerNeurons.forEach((toNeuron) => {
+        connections.value.push({
+          id: connId++,
+          x1: fromNeuron.x,
+          y1: fromNeuron.y,
+          x2: toNeuron.x,
+          y2: toNeuron.y,
+          width: Math.random() * 2 + 0.5,
+          opacity: 0.3,
+          active: false
+        })
+      })
+    })
+  }
+}
+
+const activateNeuron = (neuron) => {
+  neuron.active = !neuron.active
+  currentLayer.value = neuron.layer
+}
+
+const startForwardPropagation = async () => {
+  resetNetwork()
+
+  // 激活输入层
+  const inputNeurons = neurons.value.filter((n) => n.layer === 0)
+  inputNeurons.forEach((n) => {
+    n.active = true
+    n.radius = 25
+  })
+  currentLayer.value = 0
+
+  await sleep(500)
+
+  // 逐层激活
+  for (let l = 1; l < layers.value.length; l++) {
+    currentLayer.value = l
+    const layerNeurons = neurons.value.filter((n) => n.layer === l)
+
+    layerNeurons.forEach((neuron) => {
+      neuron.active = true
+      neuron.radius = 25
+    })
+
+    // 高亮连接
+    connections.value.forEach((conn) => {
+      const fromNeuron = neurons.value.find(
+        (n) => Math.abs(n.x - conn.x1) < 1 && Math.abs(n.y - conn.y1) < 1
+      )
+      if (fromNeuron && fromNeuron.layer === l - 1 && fromNeuron.active) {
+        conn.opacity = 0.8
+        conn.width = 3
+      }
+    })
+
+    await sleep(600)
+  }
+}
+
+const resetNetwork = () => {
+  neurons.value.forEach((n) => {
+    n.active = false
+    n.radius = 20
+  })
+  connections.value.forEach((conn) => {
+    conn.opacity = 0.3
+    conn.width = Math.random() * 2 + 0.5
+  })
+  currentLayer.value = 0
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+onMounted(() => {
+  calculateNeurons()
+  calculateConnections()
+})
+</script>
+
+<style scoped>
+.neural-network-viz-demo {
+  margin: 1rem 0;
+  padding: 1.5rem;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  color: var(--vp-c-text-1);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 1.5rem;
+}
+
+.demo-header h4 {
+  margin: 0 0 0.5rem 0;
+  color: var(--vp-c-text-1);
+  font-size: 1.5rem;
+}
+
+.demo-header p {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.network-container {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
+  margin-bottom: 1.5rem;
+  overflow-x: auto;
+}
+
+.network-svg {
+  display: block;
+  margin: 0 auto;
+  min-width: 600px;
+}
+
+.connection-line {
+  transition: all 0.3s ease;
+}
+
+.neuron-group {
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.neuron-group:hover .neuron-circle {
+  opacity: 0.9;
+}
+
+.neuron-circle {
+  fill: rgba(var(--vp-c-brand-rgb), 0.35);
+  stroke: var(--vp-c-brand);
+  stroke-width: 2;
+  transition: all 0.3s ease;
+}
+
+.neuron-group.input .neuron-circle {
+  fill: rgba(var(--vp-c-brand-rgb), 0.2);
+  stroke: var(--vp-c-brand);
+}
+
+.neuron-group.output .neuron-circle {
+  fill: rgba(var(--vp-c-brand-rgb), 0.12);
+  stroke: var(--vp-c-brand);
+}
+
+.neuron-group.active .neuron-circle {
+  stroke-width: 3;
+}
+
+.neuron-label {
+  font-size: 10px;
+  fill: var(--vp-c-text-1);
+  font-weight: 600;
+}
+
+.layer-info {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.layer-card {
+  padding: 1rem;
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.layer-card:hover {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+}
+
+.layer-card.active {
+  border-color: var(--vp-c-brand);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.layer-badge {
+  font-weight: 700;
+  color: var(--vp-c-brand);
+  margin-bottom: 0.5rem;
+}
+
+.layer-neurons {
+  font-size: 0.875rem;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.5rem;
+}
+
+.layer-desc {
+  font-size: 0.75rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.4;
+}
+
+.controls {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+}
+
+.action-btn {
+  padding: 0.75rem 2rem;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-brand);
+  border-radius: 6px;
+  font-weight: 600;
+  font-size: 1rem;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.action-btn:hover {
+  opacity: 0.95;
+}
+
+.action-btn.secondary {
+  background: var(--vp-c-bg);
+  border-color: var(--vp-c-divider);
+  color: var(--vp-c-text-1);
+}
+
+.action-btn.secondary:hover {
+  border-color: var(--vp-c-brand);
+}
+
+@media (max-width: 768px) {
+  .layer-info {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/PerceptronDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/PerceptronDemo.vue
index 13d6b78..0699368 100644
--- a/docs/.vitepress/theme/components/appendix/ai-history/PerceptronDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/ai-history/PerceptronDemo.vue
@@ -96,7 +96,7 @@ const output = computed(() => {
 .perceptron-demo {
   border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
-  background: white;
+  background: var(--vp-c-bg-soft);
   padding: 1.5rem;
   margin: 1rem 0;
   overflow-x: auto;
@@ -123,19 +123,20 @@ const output = computed(() => {
   width: 60px;
   height: 60px;
   border-radius: 50%;
-  border: 2px solid #94a3b8;
+  border: 2px solid var(--vp-c-divider);
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  background: #f1f5f9;
+  background: var(--vp-c-bg);
   position: relative;
+  color: var(--vp-c-text-1);
 }
 
 .output-node.active {
-  background: #4ade80;
-  border-color: #16a34a;
-  color: white;
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
   font-weight: bold;
 }
 
@@ -145,7 +146,7 @@ const output = computed(() => {
   top: -15px;
   width: 80px;
   text-align: center;
-  color: #64748b;
+  color: var(--vp-c-text-2);
 }
 
 .val-input {
@@ -169,7 +170,7 @@ const output = computed(() => {
 
 .weight-line {
   height: 2px;
-  background: #475569;
+  background: var(--vp-c-text-2);
   position: absolute;
   left: 0;
   right: 0;
@@ -184,9 +185,9 @@ const output = computed(() => {
   display: flex;
   align-items: center;
   gap: 4px;
-  background: white;
+  background: var(--vp-c-bg);
   padding: 2px 4px;
-  border: 1px solid #e2e8f0;
+  border: 1px solid var(--vp-c-divider);
   border-radius: 4px;
   z-index: 2;
 }
@@ -195,14 +196,14 @@ const output = computed(() => {
   width: 100px;
   height: 100px;
   border-radius: 50%;
-  background: #3b82f6;
-  color: white;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
   position: relative;
-  box-shadow: 0 4px 10px rgba(59, 130, 246, 0.3);
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.35);
 }
 
 .sum-part {
@@ -218,11 +219,11 @@ const output = computed(() => {
 .bias-control {
   position: absolute;
   bottom: -30px;
-  background: white;
-  color: #333;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
   padding: 2px 8px;
   border-radius: 10px;
-  border: 1px solid #e2e8f0;
+  border: 1px solid var(--vp-c-divider);
   font-size: 0.7rem;
   display: flex;
   align-items: center;
@@ -230,21 +231,21 @@ const output = computed(() => {
 }
 .bias-input {
   width: 30px;
-  border: 1px solid #cbd5e1;
+  border: 1px solid var(--vp-c-divider);
   border-radius: 2px;
   text-align: center;
 }
 
 .formula-bar {
   margin-top: 2rem;
-  background: #f8fafc;
+  background: var(--vp-c-bg);
   padding: 1rem;
   border-radius: 6px;
-  font-family: monospace;
+  font-family: var(--vp-font-family-mono);
   font-size: 0.8rem;
-  color: #334155;
+  color: var(--vp-c-text-1);
   text-align: center;
-  border: 1px dashed #cbd5e1;
+  border: 1px dashed var(--vp-c-divider);
 }
 
 input[type='range'] {
diff --git a/docs/.vitepress/theme/components/appendix/ai-history/RuleBasedVsLearningDemo.vue b/docs/.vitepress/theme/components/appendix/ai-history/RuleBasedVsLearningDemo.vue
index ee47c00..279125f 100644
--- a/docs/.vitepress/theme/components/appendix/ai-history/RuleBasedVsLearningDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/ai-history/RuleBasedVsLearningDemo.vue
@@ -159,19 +159,20 @@ const mlResult = computed(() => {
 }
 
 .code-block {
-  background: #1e1e2e;
-  color: #a6accd;
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-1);
   padding: 0.8rem;
   border-radius: 4px;
-  font-family: monospace;
+  font-family: var(--vp-font-family-mono);
   font-size: 0.8rem;
+  border: 1px solid var(--vp-c-divider);
 }
 
 .mini-input {
   width: 40px;
-  background: #334155;
-  border: 1px solid #475569;
-  color: white;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-1);
   border-radius: 2px;
   text-align: center;
 }
@@ -194,18 +195,18 @@ const mlResult = computed(() => {
   font-size: 1.1rem;
   padding: 0.5rem;
   border-radius: 4px;
-  background: white;
+  background: var(--vp-c-bg);
   border: 1px solid var(--vp-c-divider);
 }
 .result-box.big {
-  color: #ef4444;
-  border-color: #fecaca;
-  background: #fef2f2;
+  color: var(--vp-c-red-1, #ef4444);
+  border-color: rgba(var(--vp-c-brand-rgb), 0.18);
+  background: var(--vp-c-bg);
 }
 .result-box.small {
-  color: #db2777;
-  border-color: #fce7f3;
-  background: #fdf2f8;
+  color: var(--vp-c-text-1);
+  border-color: rgba(var(--vp-c-brand-rgb), 0.18);
+  background: var(--vp-c-bg);
 }
 
 .note {
@@ -224,24 +225,28 @@ const mlResult = computed(() => {
 }
 
 .data-point {
-  background: #e2e8f0;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
   padding: 2px 6px;
   border-radius: 4px;
   font-size: 0.7rem;
+  color: var(--vp-c-text-2);
 }
 
 .train-btn {
   width: 100%;
   padding: 0.5rem;
-  background: #3b82f6;
-  color: white;
-  border: none;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-brand);
   border-radius: 4px;
   cursor: pointer;
   transition: all 0.2s;
 }
 .train-btn:disabled {
-  background: #10b981;
-  cursor: default;
+  background: var(--vp-c-bg);
+  border-color: var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+  cursor: not-allowed;
 }
 </style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue
new file mode 100644
index 0000000..39539f0
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue
@@ -0,0 +1,395 @@
+<template>
+  <div class="api-concept-demo">
+    <!-- 标题和说明 -->
+    <div class="demo-header">
+      <h3>🍽️ API = 软件世界的"服务员"</h3>
+      <p class="subtitle">点击菜单项，观察 API 如何传递请求</p>
+    </div>
+
+    <!-- 主场景 -->
+    <div class="scene-container">
+      <!-- 顾客区域 -->
+      <div class="customer-zone">
+        <div class="customer-avatar">👤</div>
+        <div class="menu">
+          <h4>菜单</h4>
+          <button
+            v-for="item in menuItems"
+            :key="item.id"
+            @click="orderDish(item)"
+            :disabled="isProcessing"
+            class="menu-item"
+          >
+            {{ item.name }}
+          </button>
+        </div>
+      </div>
+
+      <!-- API/服务员 -->
+      <div class="api-zone">
+        <div class="waiter" :class="{ 'moving': isProcessing }">
+          <div class="waiter-avatar">🧑‍💼</div>
+          <div class="api-label">API</div>
+        </div>
+        <div class="request-flow" v-if="currentRequest">
+          <div class="flow-arrow">→</div>
+          <div class="request-info">
+            <div>请求: GET /{{ currentRequest }}</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- 厨房/服务器区域 -->
+      <div class="kitchen-zone">
+        <div class="kitchen-avatar">👨‍🍳</div>
+        <div class="kitchen-label">服务器</div>
+        <div class="status" :class="statusClass">
+          {{ statusText }}
+        </div>
+      </div>
+    </div>
+
+    <!-- 对比演示 -->
+    <div class="comparison">
+      <button @click="showComparison = !showComparison">
+        {{ showComparison ? '隐藏' : '显示' }}对比：有 API vs 无 API
+      </button>
+
+      <div v-if="showComparison" class="comparison-scene">
+        <div class="with-api">
+          <h4>✅ 有 API（服务员）</h4>
+          <div class="comparison-visual">
+            顾客 → 服务员 → 厨房
+          </div>
+          <p>秩序井然，高效清晰</p>
+        </div>
+        <div class="without-api">
+          <h4>❌ 无 API（直接冲进厨房）</h4>
+          <div class="comparison-visual chaotic">
+            顾客 厨房 👷 厨房 👨‍🍳
+          </div>
+          <p>混乱不堪，效率低下</p>
+        </div>
+      </div>
+    </div>
+
+    <!-- 关键点总结 -->
+    <div class="key-points">
+      <h4>💡 关键点</h4>
+      <ul>
+        <li>API 是软件之间的"服务员"</li>
+        <li>调用 API = 向服务员点餐</li>
+        <li>API 返回数据 = 服务员端菜上来</li>
+        <li>有了 API，软件之间可以"对话"</li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const isProcessing = ref(false)
+const currentRequest = ref(null)
+const statusText = ref('空闲')
+const showComparison = ref(false)
+
+const menuItems = [
+  { id: 1, name: '宫保鸡丁', endpoint: 'dishes/kungpao' },
+  { id: 2, name: '鱼香肉丝', endpoint: 'dishes/yuxiang' },
+  { id: 3, name: '麻婆豆腐', endpoint: 'dishes/mapo' }
+]
+
+const statusClass = computed(() => {
+  if (isProcessing.value) return 'processing'
+  return 'idle'
+})
+
+function orderDish(item) {
+  if (isProcessing.value) return
+
+  currentRequest.value = item.endpoint
+  isProcessing.value = true
+  statusText.value = '处理中...'
+
+  // 模拟 API 调用过程
+  setTimeout(() => {
+    statusText.value = '制作完成'
+    setTimeout(() => {
+      isProcessing.value = false
+      currentRequest.value = null
+      statusText.value = '空闲'
+    }, 1000)
+  }, 2000)
+}
+</script>
+
+<style scoped>
+.api-concept-demo {
+  border: 2px solid #e0e0e0;
+  border-radius: 12px;
+  padding: 24px;
+  background: linear-gradient(135deg, #f5f7fa 0%, #ffffff 100%);
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.demo-header h3 {
+  font-size: 24px;
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.subtitle {
+  color: #666;
+  font-size: 14px;
+  margin: 0;
+}
+
+.scene-container {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 24px;
+  margin: 32px 0;
+  padding: 24px;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.customer-zone,
+.kitchen-zone {
+  flex: 1;
+  text-align: center;
+  padding: 16px;
+  border-radius: 8px;
+  background: #f8f9fa;
+}
+
+.api-zone {
+  flex: 1;
+  text-align: center;
+  padding: 16px;
+  border-radius: 8px;
+  background: #fff3cd;
+  border: 2px dashed #ffc107;
+}
+
+.customer-avatar,
+.kitchen-avatar {
+  font-size: 48px;
+  margin-bottom: 8px;
+}
+
+.waiter-avatar {
+  font-size: 48px;
+  margin-bottom: 8px;
+  transition: transform 0.3s;
+}
+
+.waiter.moving .waiter-avatar {
+  animation: bounce 0.5s infinite;
+}
+
+@keyframes bounce {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-10px);
+  }
+}
+
+.api-label,
+.kitchen-label {
+  font-weight: bold;
+  color: #856404;
+  font-size: 14px;
+}
+
+.menu {
+  margin-top: 16px;
+}
+
+.menu-item {
+  display: block;
+  width: 100%;
+  padding: 8px 16px;
+  margin: 8px 0;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.menu-item:hover:not(:disabled) {
+  background: #007bff;
+  color: white;
+  border-color: #007bff;
+}
+
+.menu-item:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.status {
+  margin-top: 12px;
+  padding: 8px;
+  border-radius: 4px;
+  font-weight: bold;
+}
+
+.status.idle {
+  background: #d4edda;
+  color: #155724;
+}
+
+.status.processing {
+  background: #fff3cd;
+  color: #856404;
+  animation: pulse 1s infinite;
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.7;
+  }
+}
+
+.comparison {
+  margin-top: 24px;
+  text-align: center;
+}
+
+.comparison button {
+  padding: 8px 16px;
+  background: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.comparison button:hover {
+  background: #0056b3;
+}
+
+.comparison-scene {
+  display: flex;
+  gap: 24px;
+  margin-top: 16px;
+}
+
+.with-api,
+.without-api {
+  flex: 1;
+  padding: 16px;
+  border-radius: 8px;
+}
+
+.with-api {
+  background: #d4edda;
+}
+
+.without-api {
+  background: #f8d7da;
+}
+
+.comparison-visual {
+  font-size: 24px;
+  margin: 12px 0;
+}
+
+.comparison-visual.chaotic {
+  animation: shake 0.5s infinite;
+}
+
+@keyframes shake {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+  25% {
+    transform: translateX(-5px);
+  }
+  75% {
+    transform: translateX(5px);
+  }
+}
+
+.key-points {
+  margin-top: 24px;
+  padding: 16px;
+  background: #e7f3ff;
+  border-left: 4px solid #007bff;
+  border-radius: 4px;
+}
+
+.key-points h4 {
+  margin: 0 0 12px 0;
+  color: #007bff;
+}
+
+.key-points ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.key-points li {
+  margin: 8px 0;
+  color: #333;
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+  .api-concept-demo {
+    background: linear-gradient(135deg, #1a1a1a 0%, #2d2d2d 100%);
+    border-color: #444;
+  }
+
+  .demo-header h3 {
+    color: #e0e0e0;
+  }
+
+  .scene-container {
+    background: #2d2d2d;
+  }
+
+  .customer-zone,
+  .kitchen-zone {
+    background: #363636;
+  }
+
+  .menu-item {
+    background: #2d2d2d;
+    border-color: #555;
+    color: #e0e0e0;
+  }
+
+  .menu-item:hover:not(:disabled) {
+    background: #007bff;
+    color: white;
+  }
+
+  .key-points {
+    background: #1e3a5f;
+    border-left-color: #4dabf7;
+  }
+
+  .key-points li {
+    color: #c0c0c0;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue
new file mode 100644
index 0000000..cf41613
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue
@@ -0,0 +1,830 @@
+<template>
+  <div class="api-document-demo">
+    <div class="demo-header">
+      <h3>📚 API 文档导航</h3>
+      <p>学会像阅读菜单一样阅读 API 文档</p>
+    </div>
+
+    <!-- 文档导航 -->
+    <div class="doc-nav">
+      <button
+        v-for="tab in tabs"
+        :key="tab.id"
+        @click="activeTab = tab.id"
+        :class="{ active: activeTab === tab.id }"
+      >
+        {{ tab.icon }} {{ tab.label }}
+      </button>
+    </div>
+
+    <!-- 概述标签页 -->
+    <div v-if="activeTab === 'overview'" class="tab-content">
+      <div class="api-overview">
+        <h4>用户管理 API</h4>
+        <p>本 API 提供用户的增删改查功能，支持分页查询和高级过滤。</p>
+
+        <div class="info-cards">
+          <div class="info-card">
+            <div class="card-icon">🔗</div>
+            <div class="card-title">Base URL</div>
+            <div class="card-value"><code>https://api.example.com/v1</code></div>
+          </div>
+
+          <div class="info-card">
+            <div class="card-icon">🔑</div>
+            <div class="card-title">认证方式</div>
+            <div class="card-value">API Key 或 Bearer Token</div>
+          </div>
+
+          <div class="info-card">
+            <div class="card-icon">📊</div>
+            <div class="card-title">数据格式</div>
+            <div class="card-value">JSON</div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- 接口列表标签页 -->
+    <div v-if="activeTab === 'endpoints'" class="tab-content">
+      <div class="endpoint-list">
+        <div
+          v-for="endpoint in endpoints"
+          :key="endpoint.id"
+          @click="selectedEndpoint = endpoint"
+          :class="['endpoint-item', endpoint.method.toLowerCase(), { active: selectedEndpoint?.id === endpoint.id }]"
+        >
+          <div class="method-badge">{{ endpoint.method }}</div>
+          <div class="endpoint-path">{{ endpoint.path }}</div>
+          <div class="endpoint-desc">{{ endpoint.description }}</div>
+        </div>
+      </div>
+
+      <!-- 接口详情 -->
+      <div v-if="selectedEndpoint" class="endpoint-detail">
+        <div class="detail-header">
+          <span class="method-badge large" :class="selectedEndpoint.method.toLowerCase()">
+            {{ selectedEndpoint.method }}
+          </span>
+          <span class="endpoint-path">{{ selectedEndpoint.path }}</span>
+        </div>
+
+        <p class="detail-description">{{ selectedEndpoint.description }}</p>
+
+        <!-- 请求参数 -->
+        <div class="params-section">
+          <h5>📥 请求参数</h5>
+          <table class="params-table">
+            <thead>
+              <tr>
+                <th>参数名</th>
+                <th>类型</th>
+                <th>必填</th>
+                <th>说明</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="param in selectedEndpoint.params" :key="param.name">
+                <td><code>{{ param.name }}</code></td>
+                <td><span class="type-badge">{{ param.type }}</span></td>
+                <td>{{ param.required ? '✅ 是' : '❌ 否' }}</td>
+                <td>{{ param.description }}</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+
+        <!-- 请求示例 -->
+        <div class="example-section">
+          <h5>📤 请求示例</h5>
+          <div class="code-tabs">
+            <button
+              v-for="lang in ['curl', 'javascript', 'python']"
+              :key="lang"
+              @click="codeLang = lang"
+              :class="{ active: codeLang === lang }"
+            >
+              {{ lang }}
+            </button>
+          </div>
+          <pre class="code-block"><code>{{ getCodeExample() }}</code></pre>
+        </div>
+
+        <!-- 响应示例 -->
+        <div class="response-section">
+          <h5>📥 响应示例</h5>
+          <pre class="code-block json"><code>{{ JSON.stringify(selectedEndpoint.response, null, 2) }}</code></pre>
+        </div>
+
+        <button @click="tryApi" class="try-btn">🚀 试试这个 API</button>
+      </div>
+    </div>
+
+    <!-- 数据模型标签页 -->
+    <div v-if="activeTab === 'models'" class="tab-content">
+      <div class="models-list">
+        <div v-for="model in models" :key="model.name" class="model-card">
+          <h5>{{ model.name }}</h5>
+          <p>{{ model.description }}</p>
+          <table class="fields-table">
+            <thead>
+              <tr>
+                <th>字段</th>
+                <th>类型</th>
+                <th>说明</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="field in model.fields" :key="field.name">
+                <td><code>{{ field.name }}</code></td>
+                <td>{{ field.type }}</td>
+                <td>{{ field.description }}</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+
+    <!-- 错误码标签页 -->
+    <div v-if="activeTab === 'errors'" class="tab-content">
+      <div class="error-codes">
+        <div v-for="error in errorCodes" :key="error.code" class="error-item">
+          <div class="error-code" :class="getErrorClass(error.code)">
+            {{ error.code }}
+          </div>
+          <div class="error-info">
+            <div class="error-title">{{ error.title }}</div>
+            <div class="error-description">{{ error.description }}</div>
+            <div class="error-solution">💡 {{ error.solution }}</div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- API 测试弹窗 -->
+    <div v-if="showTestModal" class="modal-overlay" @click="showTestModal = false">
+      <div class="modal-content" @click.stop>
+        <div class="modal-header">
+          <h4>🧪 测试 API</h4>
+          <button @click="showTestModal = false" class="close-btn">×</button>
+        </div>
+        <div class="modal-body">
+          <div class="test-config">
+            <label>
+              接口地址：
+              <input v-model="testUrl" readonly />
+            </label>
+            <label v-for="param in testParams" :key="param.name">
+              {{ param.name }}：
+              <input v-model="param.value" :placeholder="param.placeholder" />
+            </label>
+          </div>
+          <button @click="sendTestRequest" class="send-btn" :disabled="testLoading">
+            {{ testLoading ? '发送中...' : '🚀 发送请求' }}
+          </button>
+
+          <div v-if="testResponse" class="test-result">
+            <h5>响应结果：</h5>
+            <pre><code>{{ JSON.stringify(testResponse, null, 2) }}</code></pre>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- 提示信息 -->
+    <div class="tips">
+      <h4>💡 阅读技巧</h4>
+      <ul>
+        <li>先看 <strong>概述</strong> 了解 API 的基本信息</li>
+        <li>再看 <strong>接口列表</strong> 找到你需要的功能</li>
+        <li>仔细看 <strong>请求参数</strong>，注意必填项和类型</li>
+        <li>参考 <strong>请求示例</strong>，复制粘贴修改</li>
+        <li>遇到错误查 <strong>错误码</strong> 快速定位问题</li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const activeTab = ref('overview')
+const selectedEndpoint = ref(null)
+const codeLang = ref('curl')
+const showTestModal = ref(false)
+const testUrl = ref('')
+const testResponse = ref(null)
+const testLoading = ref(false)
+
+const tabs = [
+  { id: 'overview', label: '概述', icon: '📖' },
+  { id: 'endpoints', label: '接口列表', icon: '🔌' },
+  { id: 'models', label: '数据模型', icon: '📊' },
+  { id: 'errors', label: '错误码', icon: '⚠️' }
+]
+
+const endpoints = [
+  {
+    id: 1,
+    method: 'GET',
+    path: '/users',
+    description: '获取用户列表（支持分页）',
+    params: [
+      { name: 'page', type: 'number', required: false, description: '页码，默认 1' },
+      { name: 'limit', type: 'number', required: false, description: '每页数量，默认 20' },
+      { name: 'search', type: 'string', required: false, description: '搜索关键词' }
+    ],
+    response: {
+      code: 200,
+      message: 'success',
+      data: [
+        { id: 1, name: '张三', email: 'zhangsan@example.com' },
+        { id: 2, name: '李四', email: 'lisi@example.com' }
+      ],
+      pagination: { page: 1, limit: 20, total: 100 }
+    }
+  },
+  {
+    id: 2,
+    method: 'POST',
+    path: '/users',
+    description: '创建新用户',
+    params: [
+      { name: 'name', type: 'string', required: true, description: '用户名' },
+      { name: 'email', type: 'string', required: true, description: '邮箱地址' },
+      { name: 'password', type: 'string', required: true, description: '密码' }
+    ],
+    response: {
+      code: 201,
+      message: 'created',
+      data: { id: 3, name: '王五', email: 'wangwu@example.com', createdAt: '2024-01-15' }
+    }
+  }
+]
+
+const models = [
+  {
+    name: 'User',
+    description: '用户对象',
+    fields: [
+      { name: 'id', type: 'number', description: '用户 ID' },
+      { name: 'name', type: 'string', description: '用户名' },
+      { name: 'email', type: 'string', description: '邮箱地址' },
+      { name: 'createdAt', type: 'string', description: '创建时间（ISO 8601）' }
+    ]
+  }
+]
+
+const errorCodes = [
+  { code: 400, title: '参数错误', description: '请求参数格式错误或缺少必填参数', solution: '检查参数名、类型和格式' },
+  { code: 401, title: '未授权', description: '缺少有效的认证信息', solution: '添加 API Key 或 Bearer Token' },
+  { code: 404, title: '资源不存在', description: '请求的资源未找到', solution: '检查 URL 路径是否正确' },
+  { code: 429, title: '请求过于频繁', description: '超过了 API 的速率限制', solution: '降低请求频率或联系提供方' },
+  { code: 500, title: '服务器错误', description: '服务器内部错误', solution: '稍后重试或联系技术支持' }
+]
+
+const testParams = ref([])
+
+function getCodeExample() {
+  if (!selectedEndpoint.value) return ''
+
+  const ep = selectedEndpoint.value
+
+  if (codeLang.value === 'curl') {
+    return `curl -X ${ep.method} \\
+  https://api.example.com/v1${ep.path} \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer YOUR_API_KEY" \\
+  ${ep.method === 'POST' ? '-d \'{"name":"张三","email":"zhangsan@example.com"}\'' : ''}`
+  }
+
+  if (codeLang.value === 'javascript') {
+    return `fetch('https://api.example.com/v1${ep.path}', {
+  method: '${ep.method}',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_API_KEY'
+  }${ep.method === 'POST' ? `,
+  body: JSON.stringify({
+    name: '张三',
+    email: 'zhangsan@example.com'
+  })` : ''}
+}).then(res => res.json())
+  .then(data => console.log(data))`
+  }
+
+  if (codeLang.value === 'python') {
+    return `import requests
+
+url = 'https://api.example.com/v1${ep.path}'
+headers = {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_API_KEY'
+}
+${ep.method === 'POST' ? 'data = {"name": "张三", "email": "zhangsan@example.com"}\n\n' : ''}response = requests.${ep.method.toLowerCase()}(url, headers=headers${ep.method === 'POST' ? ', json=data' : ''})
+
+print(response.json())`
+  }
+
+  return ''
+}
+
+function getErrorClass(code) {
+  if (code >= 200 && code < 300) return 'success'
+  if (code >= 300 && code < 400) return 'redirect'
+  if (code >= 400 && code < 500) return 'client-error'
+  return 'server-error'
+}
+
+function tryApi() {
+  if (!selectedEndpoint.value) return
+
+  testUrl.value = `https://api.example.com/v1${selectedEndpoint.value.path}`
+  testParams.value = selectedEndpoint.value.params.map(p => ({
+    name: p.name,
+    value: '',
+    placeholder: p.description
+  }))
+  testResponse.value = null
+  showTestModal.value = true
+}
+
+function sendTestRequest() {
+  testLoading.value = true
+
+  setTimeout(() => {
+    testResponse.value = selectedEndpoint.value.response
+    testLoading.value = false
+  }, 1000)
+}
+</script>
+
+<style scoped>
+.api-document-demo {
+  border: 2px solid #e0e0e0;
+  border-radius: 12px;
+  padding: 24px;
+  background: #fafafa;
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.demo-header h3 {
+  font-size: 20px;
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.doc-nav {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 24px;
+  border-bottom: 2px solid #e0e0e0;
+  padding-bottom: 16px;
+}
+
+.doc-nav button {
+  padding: 10px 20px;
+  border: 1px solid #e0e0e0;
+  border-radius: 6px;
+  background: white;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.doc-nav button:hover {
+  background: #f0f0f0;
+}
+
+.doc-nav button.active {
+  background: #007bff;
+  color: white;
+  border-color: #007bff;
+}
+
+.tab-content {
+  background: white;
+  border-radius: 8px;
+  padding: 20px;
+  min-height: 400px;
+}
+
+.api-overview h4 {
+  margin: 0 0 12px 0;
+  color: #2c3e50;
+}
+
+.info-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 16px;
+  margin-top: 20px;
+}
+
+.info-card {
+  padding: 16px;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  text-align: center;
+}
+
+.card-icon {
+  font-size: 32px;
+  margin-bottom: 8px;
+}
+
+.card-title {
+  font-weight: bold;
+  margin-bottom: 8px;
+  color: #666;
+}
+
+.endpoint-list {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  margin-bottom: 24px;
+}
+
+.endpoint-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  border: 2px solid #e0e0e0;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.endpoint-item:hover {
+  border-color: #007bff;
+  background: #f8f9fa;
+}
+
+.endpoint-item.active {
+  border-color: #007bff;
+  background: #e8f4ff;
+}
+
+.method-badge {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+  min-width: 60px;
+  text-align: center;
+}
+
+.method-badge.large {
+  font-size: 16px;
+  padding: 8px 16px;
+}
+
+.method-badge.get {
+  background: #61affe;
+  color: white;
+}
+
+.method-badge.post {
+  background: #49cc90;
+  color: white;
+}
+
+.endpoint-path {
+  font-family: monospace;
+  font-weight: bold;
+  color: #333;
+}
+
+.endpoint-desc {
+  color: #666;
+  font-size: 14px;
+}
+
+.endpoint-detail {
+  background: #f8f9fa;
+  border-radius: 8px;
+  padding: 20px;
+}
+
+.detail-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.params-section,
+.example-section,
+.response-section {
+  margin-top: 24px;
+}
+
+.params-section h5,
+.example-section h5,
+.response-section h5 {
+  margin: 0 0 12px 0;
+  font-size: 16px;
+}
+
+.params-table,
+.fields-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 16px;
+}
+
+.params-table th,
+.params-table td,
+.fields-table th,
+.fields-table td {
+  padding: 10px;
+  text-align: left;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.params-table th,
+.fields-table th {
+  background: #f0f0f0;
+  font-weight: bold;
+  font-size: 13px;
+}
+
+.type-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  background: #e0e0e0;
+  border-radius: 3px;
+  font-size: 12px;
+  font-family: monospace;
+}
+
+.code-tabs {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.code-tabs button {
+  padding: 6px 12px;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.code-tabs button.active {
+  background: #007bff;
+  color: white;
+  border-color: #007bff;
+}
+
+.code-block {
+  background: #2d2d2d;
+  color: #f8f8f2;
+  padding: 16px;
+  border-radius: 6px;
+  overflow-x: auto;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.code-block.json {
+  background: #1e1e1e;
+}
+
+.try-btn {
+  margin-top: 20px;
+  padding: 12px 24px;
+  background: #28a745;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.try-btn:hover {
+  background: #218838;
+}
+
+.model-card {
+  padding: 16px;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  margin-bottom: 16px;
+}
+
+.model-card h5 {
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.model-card p {
+  color: #666;
+  font-size: 14px;
+  margin-bottom: 12px;
+}
+
+.error-codes {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.error-item {
+  display: flex;
+  gap: 16px;
+  padding: 16px;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  background: white;
+}
+
+.error-code {
+  padding: 8px 16px;
+  border-radius: 6px;
+  font-weight: bold;
+  font-family: monospace;
+  font-size: 18px;
+  min-width: 80px;
+  text-align: center;
+}
+
+.error-code.success {
+  background: #d4edda;
+  color: #155724;
+}
+
+.error-code.client-error {
+  background: #f8d7da;
+  color: #721c24;
+}
+
+.error-code.server-error {
+  background: #f5c6cb;
+  color: #721c24;
+}
+
+.error-info {
+  flex: 1;
+}
+
+.error-title {
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.error-description {
+  color: #666;
+  font-size: 14px;
+  margin-bottom: 8px;
+}
+
+.error-solution {
+  color: #007bff;
+  font-size: 13px;
+}
+
+.modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.modal-content {
+  background: white;
+  border-radius: 12px;
+  width: 90%;
+  max-width: 600px;
+  max-height: 80vh;
+  overflow-y: auto;
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 16px 20px;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.modal-header h4 {
+  margin: 0;
+}
+
+.close-btn {
+  background: none;
+  border: none;
+  font-size: 32px;
+  cursor: pointer;
+  color: #999;
+}
+
+.close-btn:hover {
+  color: #333;
+}
+
+.modal-body {
+  padding: 20px;
+}
+
+.test-config {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  margin-bottom: 20px;
+}
+
+.test-config label {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  font-size: 14px;
+  font-weight: bold;
+}
+
+.test-config input {
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.send-btn {
+  width: 100%;
+  padding: 12px;
+  background: #007bff;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.send-btn:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.test-result {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 6px;
+}
+
+.test-result h5 {
+  margin: 0 0 12px 0;
+  font-size: 14px;
+}
+
+.test-result pre {
+  margin: 0;
+}
+
+.tips {
+  margin-top: 24px;
+  padding: 16px;
+  background: #e7f3ff;
+  border-left: 4px solid #007bff;
+  border-radius: 4px;
+}
+
+.tips h4 {
+  margin: 0 0 12px 0;
+  color: #007bff;
+}
+
+.tips ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.tips li {
+  margin: 8px 0;
+  line-height: 1.6;
+}
+
+code {
+  background: #f8f9fa;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 12px;
+  color: #e83e8c;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue
new file mode 100644
index 0000000..a5d9c4a
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue
@@ -0,0 +1,615 @@
+<template>
+  <div class="api-method-demo">
+    <div class="demo-header">
+      <h3>🎯 HTTP 方法：四种基本操作</h3>
+      <p>点击不同方法，观察对数据的影响</p>
+    </div>
+
+    <!-- 方法选择器 -->
+    <div class="method-selector">
+      <button
+        v-for="method in methods"
+        :key="method.name"
+        @click="selectMethod(method)"
+        :class="['method-card', method.name.toLowerCase(), { active: selectedMethod?.name === method.name }]"
+      >
+        <div class="method-icon">{{ method.icon }}</div>
+        <div class="method-name">{{ method.name }}</div>
+        <div class="method-label">{{ method.label }}</div>
+        <div class="method-analogy">{{ method.analogy }}</div>
+      </button>
+    </div>
+
+    <!-- 演示区域 -->
+    <div class="demo-area" v-if="selectedMethod">
+      <!-- 左侧：请求详情 -->
+      <div class="request-panel">
+        <h4>📤 请求</h4>
+        <div class="request-line">
+          <span class="http-method" :class="selectedMethod.name.toLowerCase()">
+            {{ selectedMethod.name }}
+          </span>
+          <span class="url">{{ getMockUrl() }}</span>
+        </div>
+
+        <div v-if="selectedMethod.name !== 'GET'" class="request-body">
+          <div class="panel-title">Request Body:</div>
+          <pre><code>{{ getMockBody() }}</code></pre>
+        </div>
+      </div>
+
+      <!-- 右侧：响应详情 -->
+      <div class="response-panel">
+        <h4>📥 响应</h4>
+        <div class="status-line">
+          <span class="status-code" :class="getStatusClass()">
+            {{ getMockStatus() }}
+          </span>
+          <span class="status-text">{{ getMockStatusText() }}</span>
+        </div>
+
+        <div class="response-body">
+          <div class="panel-title">Response Body:</div>
+          <pre><code>{{ getMockResponse() }}</code></pre>
+        </div>
+      </div>
+    </div>
+
+    <!-- 数据展示区 -->
+    <div class="data-view">
+      <h4>👥 用户数据</h4>
+      <div class="user-list">
+        <div v-for="user in users" :key="user.id" class="user-card">
+          <div class="user-avatar">{{ user.avatar }}</div>
+          <div class="user-info">
+            <div class="user-name">{{ user.name }}</div>
+            <div class="user-email">{{ user.email }}</div>
+          </div>
+          <div class="user-actions">
+            <button @click="editUser(user)" class="btn-edit">✏️</button>
+            <button @click="deleteUser(user.id)" class="btn-delete">❌</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="action-bar">
+        <button @click="addNewUser" class="btn-add">
+          <span>+ POST /users</span>
+          <span class="hint">添加新用户</span>
+        </button>
+      </div>
+    </div>
+
+    <!-- 方法对比表 -->
+    <div class="comparison-table">
+      <h4>📊 方法对比</h4>
+      <table>
+        <thead>
+          <tr>
+            <th>方法</th>
+            <th>作用</th>
+            <th>餐厅类比</th>
+            <th>幂等性</th>
+            <th>示例</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="method in methods" :key="method.name">
+            <td><span :class="['badge', method.name.toLowerCase()]">{{ method.name }}</span></td>
+            <td>{{ method.label }}</td>
+            <td>{{ method.analogy }}</td>
+            <td>{{ method.idempotent ? '✅ 是' : '❌ 否' }}</td>
+            <td><code>{{ method.example }}</code></td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const selectedMethod = ref(null)
+
+const methods = [
+  {
+    name: 'GET',
+    label: '获取数据',
+    icon: '📋',
+    analogy: '查看菜单',
+    idempotent: true,
+    example: 'GET /users'
+  },
+  {
+    name: 'POST',
+    label: '创建数据',
+    icon: '🍽️',
+    analogy: '点新菜',
+    idempotent: false,
+    example: 'POST /users'
+  },
+  {
+    name: 'PUT',
+    label: '更新数据',
+    icon: '✏️',
+    analogy: '修改订单',
+    idempotent: true,
+    example: 'PUT /users/1'
+  },
+  {
+    name: 'DELETE',
+    label: '删除数据',
+    icon: '❌',
+    analogy: '取消订单',
+    idempotent: true,
+    example: 'DELETE /users/1'
+  }
+]
+
+// 模拟用户数据
+const users = ref([
+  { id: 1, name: '张三', email: 'zhangsan@example.com', avatar: '👨' },
+  { id: 2, name: '李四', email: 'lisi@example.com', avatar: '👩' },
+  { id: 3, name: '王五', email: 'wangwu@example.com', avatar: '👨‍💼' }
+])
+
+function selectMethod(method) {
+  selectedMethod.value = method
+}
+
+function getMockUrl() {
+  const baseUrl = '/api/users'
+  if (selectedMethod.value.name === 'GET' && users.value.length > 0) {
+    return `${baseUrl}/${users.value[0].id}`
+  }
+  return baseUrl
+}
+
+function getMockBody() {
+  if (selectedMethod.value.name === 'POST') {
+    return JSON.stringify(
+      {
+        name: '赵六',
+        email: 'zhaoliu@example.com'
+      },
+      null,
+      2
+    )
+  }
+  if (selectedMethod.value.name === 'PUT') {
+    return JSON.stringify(
+      {
+        name: '张三（已修改）',
+        email: 'zhangsan_new@example.com'
+      },
+      null,
+      2
+    )
+  }
+  return ''
+}
+
+function getMockStatus() {
+  const statusMap = {
+    GET: 200,
+    POST: 201,
+    PUT: 200,
+    DELETE: 204
+  }
+  return statusMap[selectedMethod.value.name] || 200
+}
+
+function getMockStatusText() {
+  const textMap = {
+    200: 'OK',
+    201: 'Created',
+    204: 'No Content'
+  }
+  return textMap[getMockStatus()] || 'OK'
+}
+
+function getStatusClass() {
+  const status = getMockStatus()
+  if (status >= 200 && status < 300) return 'success'
+  if (status >= 300 && status < 400) return 'redirect'
+  if (status >= 400 && status < 500) return 'client-error'
+  return 'server-error'
+}
+
+function getMockResponse() {
+  if (selectedMethod.value.name === 'DELETE') {
+    return '(无返回内容)'
+  }
+
+  if (selectedMethod.value.name === 'GET') {
+    return JSON.stringify(users.value[0] || {}, null, 2)
+  }
+
+  if (selectedMethod.value.name === 'POST') {
+    return JSON.stringify(
+      {
+        id: 4,
+        name: '赵六',
+        email: 'zhaoliu@example.com',
+        createdAt: '2024-01-15T10:30:00Z'
+      },
+      null,
+      2
+    )
+  }
+
+  if (selectedMethod.value.name === 'PUT') {
+    return JSON.stringify(
+      {
+        id: 1,
+        name: '张三（已修改）',
+        email: 'zhangsan_new@example.com',
+        updatedAt: '2024-01-15T10:30:00Z'
+      },
+      null,
+      2
+    )
+  }
+
+  return '{}'
+}
+
+function addNewUser() {
+  selectMethod(methods[1]) // POST
+}
+
+function editUser(user) {
+  selectMethod(methods[2]) // PUT
+}
+
+function deleteUser(userId) {
+  selectMethod(methods[3]) // DELETE
+}
+</script>
+
+<style scoped>
+.api-method-demo {
+  border: 2px solid #e0e0e0;
+  border-radius: 12px;
+  padding: 24px;
+  background: #fafafa;
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.demo-header h3 {
+  font-size: 20px;
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.method-selector {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.method-card {
+  padding: 20px;
+  border: 2px solid #e0e0e0;
+  border-radius: 8px;
+  background: white;
+  cursor: pointer;
+  transition: all 0.3s;
+  text-align: center;
+}
+
+.method-card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+.method-card.active {
+  border-width: 3px;
+}
+
+.method-card.get {
+  border-color: #61affe;
+}
+.method-card.get.active {
+  background: #e8f4ff;
+}
+
+.method-card.post {
+  border-color: #49cc90;
+}
+.method-card.post.active {
+  background: #e8fff5;
+}
+
+.method-card.put {
+  border-color: #fca130;
+}
+.method-card.put.active {
+  background: #fff8e8;
+}
+
+.method-card.delete {
+  border-color: #f93e3e;
+}
+.method-card.delete.active {
+  background: #ffe8e8;
+}
+
+.method-icon {
+  font-size: 36px;
+  margin-bottom: 8px;
+}
+
+.method-name {
+  font-size: 24px;
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.method-label {
+  color: #666;
+  font-size: 14px;
+  margin-bottom: 4px;
+}
+
+.method-analogy {
+  color: #999;
+  font-size: 12px;
+}
+
+.demo-area {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.request-panel,
+.response-panel {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.request-line {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 16px;
+  padding: 12px;
+  background: #f8f9fa;
+  border-radius: 4px;
+}
+
+.http-method {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+}
+
+.http-method.get {
+  background: #61affe;
+  color: white;
+}
+.http-method.post {
+  background: #49cc90;
+  color: white;
+}
+.http-method.put {
+  background: #fca130;
+  color: white;
+}
+.http-method.delete {
+  background: #f93e3e;
+  color: white;
+}
+
+.url {
+  font-family: monospace;
+  color: #333;
+}
+
+.panel-title {
+  font-size: 12px;
+  color: #666;
+  margin-bottom: 8px;
+  font-weight: bold;
+}
+
+.request-panel pre,
+.response-panel pre {
+  background: #f8f9fa;
+  padding: 12px;
+  border-radius: 4px;
+  overflow-x: auto;
+  font-size: 13px;
+  margin: 0;
+}
+
+.status-line {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.status-code {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+}
+
+.status-code.success {
+  background: #d4edda;
+  color: #155724;
+}
+.status-code.redirect {
+  background: #fff3cd;
+  color: #856404;
+}
+.status-code.client-error {
+  background: #f8d7da;
+  color: #721c24;
+}
+.status-code.server-error {
+  background: #f5c6cb;
+  color: #721c24;
+}
+
+.data-view {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+  margin-bottom: 24px;
+}
+
+.user-list {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.user-card {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  background: #fafafa;
+}
+
+.user-avatar {
+  font-size: 32px;
+}
+
+.user-info {
+  flex: 1;
+}
+
+.user-name {
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.user-email {
+  font-size: 12px;
+  color: #666;
+}
+
+.user-actions {
+  display: flex;
+  gap: 8px;
+}
+
+.btn-edit,
+.btn-delete {
+  padding: 4px 8px;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 16px;
+  background: white;
+  transition: all 0.2s;
+}
+
+.btn-edit:hover {
+  background: #fff3cd;
+}
+.btn-delete:hover {
+  background: #f8d7da;
+}
+
+.action-bar {
+  text-align: center;
+}
+
+.btn-add {
+  padding: 12px 24px;
+  background: #49cc90;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  font-size: 14px;
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+
+.btn-add:hover {
+  background: #3db880;
+}
+
+.btn-add .hint {
+  font-size: 11px;
+  opacity: 0.8;
+}
+
+.comparison-table {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.comparison-table table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.comparison-table th,
+.comparison-table td {
+  padding: 12px;
+  text-align: left;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.comparison-table th {
+  background: #f8f9fa;
+  font-weight: bold;
+}
+
+.badge {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+  font-size: 13px;
+}
+
+.badge.get {
+  background: #61affe;
+  color: white;
+}
+.badge.post {
+  background: #49cc90;
+  color: white;
+}
+.badge.put {
+  background: #fca130;
+  color: white;
+}
+.badge.delete {
+  background: #f93e3e;
+  color: white;
+}
+
+code {
+  background: #f8f9fa;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 12px;
+  color: #e83e8c;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue
new file mode 100644
index 0000000..d1107b8
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue
@@ -0,0 +1,856 @@
+<template>
+  <div class="api-playground">
+    <div class="playground-header">
+      <h3>🎮 API 调用游乐场</h3>
+      <p>像使用 Postman 一样测试 API</p>
+    </div>
+
+    <!-- 预设场景 -->
+    <div class="presets">
+      <span class="presets-label">快速场景：</span>
+      <button
+        v-for="preset in presets"
+        :key="preset.id"
+        @click="loadPreset(preset)"
+        class="preset-btn"
+      >
+        {{ preset.icon }} {{ preset.name }}
+      </button>
+    </div>
+
+    <div class="playground-container">
+      <!-- 左侧：请求配置 -->
+      <div class="request-panel">
+        <div class="panel-header">
+          <h4>📤 请求</h4>
+          <button @click="sendRequest" class="send-btn" :disabled="isLoading">
+            {{ isLoading ? '发送中...' : '🚀 发送请求' }}
+          </button>
+        </div>
+
+        <!-- 请求行 -->
+        <div class="request-line">
+          <select v-model="request.method" class="method-select">
+            <option value="GET">GET</option>
+            <option value="POST">POST</option>
+            <option value="PUT">PUT</option>
+            <option value="DELETE">DELETE</option>
+          </select>
+          <input
+            v-model="request.url"
+            class="url-input"
+            placeholder="https://api.example.com/users"
+          />
+        </div>
+
+        <!-- 标签页 -->
+        <div class="request-tabs">
+          <button
+            v-for="tab in ['headers', 'body', 'auth']"
+            :key="tab"
+            @click="activeTab = tab"
+            :class="{ active: activeTab === tab }"
+            class="tab-btn"
+          >
+            {{ tab.toUpperCase() }}
+          </button>
+        </div>
+
+        <!-- Headers 编辑器 -->
+        <div v-if="activeTab === 'headers'" class="tab-content">
+          <div class="key-value-editor">
+            <div v-for="(header, index) in request.headers" :key="index" class="kv-row">
+              <input v-model="header.key" placeholder="Header 名称" />
+              <input v-model="header.value" placeholder="Header 值" />
+              <button @click="removeHeader(index)" class="remove-btn">×</button>
+            </div>
+            <button @click="addHeader" class="add-btn">+ 添加 Header</button>
+          </div>
+        </div>
+
+        <!-- Body 编辑器 -->
+        <div v-if="activeTab === 'body'" class="tab-content">
+          <div class="body-toolbar">
+            <button @click="formatBody" class="tool-btn">✨ 格式化</button>
+            <button @click="minifyBody" class="tool-btn">🗜️ 压缩</button>
+            <button @click="copyBody" class="tool-btn">📋 复制</button>
+          </div>
+          <textarea
+            v-model="request.body"
+            class="body-editor"
+            placeholder='{"key": "value"}'
+            spellcheck="false"
+          ></textarea>
+          <div v-if="bodyError" class="error-message">
+            ⚠️ JSON 格式错误：{{ bodyError }}
+          </div>
+        </div>
+
+        <!-- Auth 编辑器 -->
+        <div v-if="activeTab === 'auth'" class="tab-content">
+          <div class="auth-section">
+            <label>
+              <input type="radio" v-model="authType" value="none" />
+              无认证
+            </label>
+            <label>
+              <input type="radio" v-model="authType" value="apikey" />
+              API Key
+            </label>
+            <label>
+              <input type="radio" v-model="authType" value="bearer" />
+              Bearer Token
+            </label>
+          </div>
+
+          <div v-if="authType === 'apikey'" class="auth-inputs">
+            <input v-model="auth.apikey.name" placeholder="X-API-Key" />
+            <input v-model="auth.apikey.value" placeholder="your-api-key" />
+          </div>
+
+          <div v-if="authType === 'bearer'" class="auth-inputs">
+            <input v-model="auth.bearer.token" placeholder="your-bearer-token" />
+          </div>
+        </div>
+      </div>
+
+      <!-- 右侧：响应展示 -->
+      <div class="response-panel">
+        <div class="panel-header">
+          <h4>📥 响应</h4>
+          <div v-if="response" class="response-meta">
+            <span class="status-badge" :class="getStatusClass(response.status)">
+              {{ response.status }}
+            </span>
+            <span class="response-time">{{ responseTime }}ms</span>
+            <span class="response-size">{{ responseSize }}B</span>
+          </div>
+        </div>
+
+        <div v-if="!response && !isLoading" class="empty-state">
+          <div class="empty-icon">📡</div>
+          <p>点击"发送请求"开始测试</p>
+        </div>
+
+        <div v-if="isLoading" class="loading-state">
+          <div class="spinner"></div>
+          <p>请求发送中...</p>
+        </div>
+
+        <div v-if="response" class="response-content">
+          <pre class="response-body"><code>{{ formatJson(response.data) }}</code></pre>
+        </div>
+      </div>
+    </div>
+
+    <!-- 历史记录 -->
+    <div class="history-section">
+      <div class="history-header">
+        <h4>📜 历史记录</h4>
+        <button @click="clearHistory" class="clear-btn">清空</button>
+      </div>
+      <div class="history-list">
+        <div
+          v-for="(item, index) in history"
+          :key="index"
+          @click="loadFromHistory(item)"
+          class="history-item"
+        >
+          <span class="history-method" :class="item.method.toLowerCase()">
+            {{ item.method }}
+          </span>
+          <span class="history-url">{{ truncateUrl(item.url) }}</span>
+          <span class="history-time">{{ formatTime(item.timestamp) }}</span>
+          <span class="history-status" :class="getStatusClass(item.status)">
+            {{ item.status }}
+          </span>
+        </div>
+        <div v-if="history.length === 0" class="history-empty">
+          暂无历史记录
+        </div>
+      </div>
+    </div>
+
+    <!-- 提示信息 -->
+    <div class="tips">
+      <h4>💡 使用技巧</h4>
+      <ul>
+        <li>🎯 使用<strong>快速场景</strong>快速填充常用配置</li>
+        <li>✨ 点击<strong>格式化</strong>按钮美化 JSON</li>
+        <li>📋 查看历史记录可以快速重发之前的请求</li>
+        <li>🔒 在 Auth 标签页中添加 API Key 或 Token</li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, watch } from 'vue'
+
+const isLoading = ref(false)
+const activeTab = ref('headers')
+const authType = ref('none')
+const response = ref(null)
+const responseTime = ref(0)
+const responseSize = ref(0)
+const bodyError = ref('')
+
+const request = ref({
+  method: 'GET',
+  url: 'https://api.example.com/users',
+  headers: [
+    { key: 'Content-Type', value: 'application/json' }
+  ],
+  body: '{\n  "name": "张三",\n  "email": "zhangsan@example.com"\n}'
+})
+
+const auth = ref({
+  apikey: { name: 'X-API-Key', value: '' },
+  bearer: { token: '' }
+})
+
+const history = ref([])
+
+const presets = [
+  {
+    id: 1,
+    name: '获取用户列表',
+    icon: '👥',
+    method: 'GET',
+    url: 'https://api.example.com/users',
+    headers: [{ key: 'Content-Type', value: 'application/json' }],
+    body: ''
+  },
+  {
+    id: 2,
+    name: '创建用户',
+    icon: '➕',
+    method: 'POST',
+    url: 'https://api.example.com/users',
+    headers: [{ key: 'Content-Type', value: 'application/json' }],
+    body: '{\n  "name": "李四",\n  "email": "lisi@example.com",\n  "password": "123456"\n}'
+  },
+  {
+    id: 3,
+    name: '更新用户',
+    icon: '✏️',
+    method: 'PUT',
+    url: 'https://api.example.com/users/1',
+    headers: [{ key: 'Content-Type', value: 'application/json' }],
+    body: '{\n  "name": "张三（已修改）",\n  "email": "new_zhangsan@example.com"\n}'
+  },
+  {
+    id: 4,
+    name: '删除用户',
+    icon: '❌',
+    method: 'DELETE',
+    url: 'https://api.example.com/users/1',
+    headers: [{ key: 'Content-Type', value: 'application/json' }],
+    body: ''
+  }
+]
+
+// 模拟响应数据
+const mockResponses = {
+  'GET:https://api.example.com/users': {
+    status: 200,
+    data: {
+      code: 200,
+      message: 'success',
+      data: [
+        { id: 1, name: '张三', email: 'zhangsan@example.com' },
+        { id: 2, name: '李四', email: 'lisi@example.com' }
+      ],
+      pagination: { page: 1, limit: 20, total: 2 }
+    }
+  },
+  'POST:https://api.example.com/users': {
+    status: 201,
+    data: {
+      code: 201,
+      message: 'created',
+      data: { id: 3, name: '李四', email: 'lisi@example.com', createdAt: '2024-01-15T10:30:00Z' }
+    }
+  },
+  'PUT:https://api.example.com/users/1': {
+    status: 200,
+    data: {
+      code: 200,
+      message: 'updated',
+      data: { id: 1, name: '张三（已修改）', email: 'new_zhangsan@example.com', updatedAt: '2024-01-15T10:30:00Z' }
+    }
+  },
+  'DELETE:https://api.example.com/users/1': {
+    status: 204,
+    data: { code: 204, message: 'deleted' }
+  }
+}
+
+function loadPreset(preset) {
+  request.value = {
+    method: preset.method,
+    url: preset.url,
+    headers: [...preset.headers],
+    body: preset.body
+  }
+  activeTab.value = 'headers'
+}
+
+async function sendRequest() {
+  if (isLoading.value) return
+
+  // 验证 JSON 格式
+  if (request.value.method !== 'GET' && request.value.body.trim()) {
+    try {
+      JSON.parse(request.value.body)
+      bodyError.value = ''
+    } catch (e) {
+      bodyError.value = e.message
+      return
+    }
+  }
+
+  isLoading.value = true
+  response.value = null
+
+  const startTime = Date.now()
+
+  // 模拟网络请求
+  await sleep(1000 + Math.random() * 1000)
+
+  const key = `${request.value.method}:${request.value.url}`
+  const mockResponse = mockResponses[key] || {
+    status: 200,
+    data: { code: 200, message: 'OK', data: {} }
+  }
+
+  responseTime.value = Date.now() - startTime
+  responseSize.value = JSON.stringify(mockResponse.data).length
+  response.value = mockResponse
+
+  // 添加到历史记录
+  history.value.unshift({
+    ...request.value,
+    status: mockResponse.status,
+    timestamp: Date.now()
+  })
+
+  if (history.value.length > 10) {
+    history.value = history.value.slice(0, 10)
+  }
+
+  isLoading.value = false
+}
+
+function formatBody() {
+  try {
+    const parsed = JSON.parse(request.value.body)
+    request.value.body = JSON.stringify(parsed, null, 2)
+    bodyError.value = ''
+  } catch (e) {
+    bodyError.value = e.message
+  }
+}
+
+function minifyBody() {
+  try {
+    const parsed = JSON.parse(request.value.body)
+    request.value.body = JSON.stringify(parsed)
+    bodyError.value = ''
+  } catch (e) {
+    bodyError.value = e.message
+  }
+}
+
+function copyBody() {
+  navigator.clipboard.writeText(request.value.body)
+}
+
+function addHeader() {
+  request.value.headers.push({ key: '', value: '' })
+}
+
+function removeHeader(index) {
+  request.value.headers.splice(index, 1)
+}
+
+function formatJson(data) {
+  return JSON.stringify(data, null, 2)
+}
+
+function getStatusClass(status) {
+  if (status >= 200 && status < 300) return 'success'
+  if (status >= 300 && status < 400) return 'redirect'
+  if (status >= 400 && status < 500) return 'client-error'
+  return 'server-error'
+}
+
+function truncateUrl(url) {
+  return url.length > 40 ? url.substring(0, 40) + '...' : url
+}
+
+function formatTime(timestamp) {
+  const date = new Date(timestamp)
+  return date.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit', second: '2-digit' })
+}
+
+function loadFromHistory(item) {
+  request.value = {
+    method: item.method,
+    url: item.url,
+    headers: [...item.headers],
+    body: item.body
+  }
+}
+
+function clearHistory() {
+  history.value = []
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// 监听 auth 类型变化，自动添加 headers
+watch(authType, (newType) => {
+  if (newType === 'apikey') {
+    request.value.headers.push({ key: auth.value.apikey.name, value: auth.value.apikey.value })
+  } else if (newType === 'bearer') {
+    request.value.headers.push({ key: 'Authorization', value: `Bearer ${auth.value.bearer.token}` })
+  }
+})
+</script>
+
+<style scoped>
+.api-playground {
+  border: 2px solid #e0e0e0;
+  border-radius: 12px;
+  padding: 24px;
+  background: #fafafa;
+}
+
+.playground-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.playground-header h3 {
+  font-size: 20px;
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.presets {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 20px;
+  padding: 16px;
+  background: white;
+  border-radius: 8px;
+  flex-wrap: wrap;
+}
+
+.presets-label {
+  font-weight: bold;
+  color: #666;
+}
+
+.preset-btn {
+  padding: 8px 16px;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  background: white;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.preset-btn:hover {
+  background: #007bff;
+  color: white;
+  border-color: #007bff;
+}
+
+.playground-container {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
+  margin-bottom: 24px;
+}
+
+.request-panel,
+.response-panel {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.panel-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+}
+
+.panel-header h4 {
+  margin: 0;
+  font-size: 16px;
+}
+
+.send-btn {
+  padding: 8px 16px;
+  background: #28a745;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.send-btn:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.request-line {
+  display: flex;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.method-select {
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  font-weight: bold;
+  font-family: monospace;
+  cursor: pointer;
+}
+
+.url-input {
+  flex: 1;
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  font-family: monospace;
+}
+
+.request-tabs {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 16px;
+  border-bottom: 1px solid #e0e0e0;
+  padding-bottom: 8px;
+}
+
+.tab-btn {
+  padding: 6px 12px;
+  border: none;
+  background: none;
+  cursor: pointer;
+  color: #666;
+  font-size: 14px;
+  border-bottom: 2px solid transparent;
+}
+
+.tab-btn.active {
+  color: #007bff;
+  border-bottom-color: #007bff;
+}
+
+.tab-content {
+  min-height: 200px;
+}
+
+.key-value-editor {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.kv-row {
+  display: flex;
+  gap: 8px;
+}
+
+.kv-row input {
+  flex: 1;
+  padding: 8px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+}
+
+.remove-btn {
+  padding: 4px 12px;
+  background: #dc3545;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.add-btn {
+  padding: 8px 16px;
+  background: #28a745;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.body-toolbar {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.tool-btn {
+  padding: 4px 12px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.tool-btn:hover {
+  background: #f0f0f0;
+}
+
+.body-editor {
+  width: 100%;
+  min-height: 200px;
+  padding: 12px;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  font-family: 'Monaco', 'Menlo', monospace;
+  font-size: 13px;
+  resize: vertical;
+}
+
+.error-message {
+  margin-top: 8px;
+  padding: 8px;
+  background: #f8d7da;
+  color: #721c24;
+  border-radius: 4px;
+  font-size: 13px;
+}
+
+.auth-section {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.auth-section label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.auth-inputs {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.auth-inputs input {
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+}
+
+.response-meta {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  font-size: 13px;
+}
+
+.status-badge {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+}
+
+.status-badge.success { background: #d4edda; color: #155724; }
+.status-badge.redirect { background: #fff3cd; color: #856404; }
+.status-badge.client-error { background: #f8d7da; color: #721c24; }
+.status-badge.server-error { background: #f5c6cb; color: #721c24; }
+
+.empty-state,
+.loading-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 200px;
+  color: #999;
+}
+
+.empty-icon {
+  font-size: 48px;
+  margin-bottom: 12px;
+}
+
+.spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid #f3f3f3;
+  border-top: 4px solid #007bff;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+  margin-bottom: 12px;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+
+.response-content {
+  max-height: 400px;
+  overflow-y: auto;
+}
+
+.response-body {
+  background: #2d2d2d;
+  color: #f8f8f2;
+  padding: 16px;
+  border-radius: 6px;
+  overflow-x: auto;
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 0;
+}
+
+.history-section {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+  margin-bottom: 24px;
+}
+
+.history-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+}
+
+.history-header h4 {
+  margin: 0;
+  font-size: 16px;
+}
+
+.clear-btn {
+  padding: 4px 12px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.clear-btn:hover {
+  background: #f0f0f0;
+}
+
+.history-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.history-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px;
+  border: 1px solid #e0e0e0;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.history-item:hover {
+  background: #f8f9fa;
+  border-color: #007bff;
+}
+
+.history-method {
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-family: monospace;
+  font-size: 12px;
+  min-width: 60px;
+  text-align: center;
+}
+
+.history-method.get { background: #61affe; color: white; }
+.history-method.post { background: #49cc90; color: white; }
+.history-method.put { background: #fca130; color: white; }
+.history-method.delete { background: #f93e3e; color: white; }
+
+.history-url {
+  flex: 1;
+  font-family: monospace;
+  font-size: 13px;
+  color: #333;
+}
+
+.history-time {
+  font-size: 12px;
+  color: #999;
+}
+
+.history-status {
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-weight: bold;
+  font-size: 12px;
+}
+
+.history-status.success { background: #d4edda; color: #155724; }
+.history-status.client-error { background: #f8d7da; color: #721c24; }
+
+.history-empty {
+  padding: 20px;
+  text-align: center;
+  color: #999;
+}
+
+.tips {
+  padding: 16px;
+  background: #e7f3ff;
+  border-left: 4px solid #007bff;
+  border-radius: 4px;
+}
+
+.tips h4 {
+  margin: 0 0 12px 0;
+  color: #007bff;
+}
+
+.tips ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.tips li {
+  margin: 8px 0;
+  line-height: 1.6;
+}
+
+@media (max-width: 768px) {
+  .playground-container {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue
new file mode 100644
index 0000000..8dcadf0
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue
@@ -0,0 +1,725 @@
+<template>
+  <div class="api-quick-start-demo">
+    <div class="demo-header">
+      <h2>⚡ API 快速入门</h2>
+      <p class="subtitle">3 分钟理解 API 是什么</p>
+    </div>
+
+    <!-- 场景选择器 -->
+    <div class="scene-selector">
+      <button
+        v-for="scene in scenes"
+        :key="scene.id"
+        @click="switchScene(scene.id)"
+        :class="{ active: currentScene === scene.id }"
+        class="scene-btn"
+      >
+        {{ scene.icon }} {{ scene.name }}
+      </button>
+    </div>
+
+    <!-- 主演示区域 -->
+    <div class="demo-stage">
+      <!-- 客户端 -->
+      <div class="client-zone">
+        <div class="phone-frame">
+          <div class="phone-screen">
+            <div class="app-header">{{ getSceneData().appTitle }}</div>
+            <div class="app-content">
+              <!-- 外卖点餐场景 -->
+              <div v-if="currentScene === 'delivery'" class="delivery-ui">
+                <div class="restaurant-info">
+                  <div class="restaurant-name">🍔 汉堡王</div>
+                  <div class="dish-list">
+                    <div class="dish-item">
+                      <span class="dish-name">牛肉汉堡</span>
+                      <span class="dish-price">¥35</span>
+                    </div>
+                    <div class="dish-item">
+                      <span class="dish-name">薯条</span>
+                      <span class="dish-price">¥12</span>
+                    </div>
+                  </div>
+                </div>
+                <button @click="placeOrder" :disabled="isProcessing" class="order-btn">
+                  {{ isProcessing ? '配送中...' : '🛒 立即下单' }}
+                </button>
+              </div>
+
+              <!-- 微信登录场景 -->
+              <div v-if="currentScene === 'wechat'" class="wechat-ui">
+                <div class="login-logo">👤</div>
+                <div class="login-title">欢迎登录</div>
+                <button @click="wechatLogin" :disabled="isProcessing" class="login-btn">
+                  <span class="wechat-icon">💬</span>
+                  {{ isProcessing ? '登录中...' : '微信快速登录' }}
+                </button>
+              </div>
+
+              <!-- 天气查询场景 -->
+              <div v-if="currentScene === 'weather'" class="weather-ui">
+                <div class="weather-search">
+                  <input
+                    v-model="searchCity"
+                    placeholder="输入城市名称"
+                    class="search-input"
+                    @keyup.enter="searchWeather"
+                  />
+                  <button @click="searchWeather" :disabled="isProcessing" class="search-btn">
+                    {{ isProcessing ? '查询中...' : '🔍 查询' }}
+                  </button>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+        <div class="zone-label">👤 客户端 (你)</div>
+      </div>
+
+      <!-- API 中间层 -->
+      <div class="api-zone">
+        <div class="api-container">
+          <div class="api-icon" :class="{ moving: isProcessing }">
+            {{ getSceneData().apiIcon }}
+          </div>
+          <div class="api-label">API</div>
+          <div v-if="isProcessing" class="data-flow">
+            <div class="data-packet">{{ getSceneData().requestData }}</div>
+          </div>
+        </div>
+        <div class="zone-label">🔗 API (桥梁)</div>
+      </div>
+
+      <!-- 服务器 -->
+      <div class="server-zone">
+        <div class="server-container">
+          <div class="server-icon">🏢</div>
+          <div class="server-label">{{ getSceneData().serverName }}</div>
+          <div v-if="isProcessing && currentStep >= 3" class="processing-indicator">
+            <div class="dots">
+              <span></span><span></span><span></span>
+            </div>
+            <div class="processing-text">处理中...</div>
+          </div>
+          <div v-if="response && !isProcessing" class="result-display">
+            <div class="result-label">返回数据：</div>
+            <pre class="result-data">{{ formatResponse(response) }}</pre>
+          </div>
+        </div>
+        <div class="zone-label">🖥️ 服务器</div>
+      </div>
+    </div>
+
+    <!-- 流程说明 -->
+    <div class="flow-explanation">
+      <div class="step" :class="{ active: currentStep >= 1 }">
+        <div class="step-number">1</div>
+        <div class="step-text">发起请求</div>
+      </div>
+      <div class="arrow">→</div>
+      <div class="step" :class="{ active: currentStep >= 2 }">
+        <div class="step-number">2</div>
+        <div class="step-text">API 传递</div>
+      </div>
+      <div class="arrow">→</div>
+      <div class="step" :class="{ active: currentStep >= 3 }">
+        <div class="step-number">3</div>
+        <div class="step-text">服务器处理</div>
+      </div>
+      <div class="arrow">→</div>
+      <div class="step" :class="{ active: currentStep >= 4 }">
+        <div class="step-number">4</div>
+        <div class="step-text">返回结果</div>
+      </div>
+    </div>
+
+    <!-- 关键要点 -->
+    <div class="key-points">
+      <h4>💡 理解 API 的三个关键点</h4>
+      <div class="points-grid">
+        <div class="point-card">
+          <div class="point-icon">🔌</div>
+          <div class="point-title">API 是"接口"</div>
+          <div class="point-desc">就像插头连接电器，API 连接不同的软件系统</div>
+        </div>
+        <div class="point-card">
+          <div class="point-icon">📨</div>
+          <div class="point-title">API 是"信使"</div>
+          <div class="point-desc">你告诉 API 需要什么，API 去服务器取来给你</div>
+        </div>
+        <div class="point-card">
+          <div class="point-icon">📋</div>
+          <div class="point-title">API 是"菜单"</div>
+          <div class="point-desc">API 文档告诉你有哪些功能可以调用</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const currentScene = ref('delivery')
+const isProcessing = ref(false)
+const currentStep = ref(0)
+const response = ref(null)
+const searchCity = ref('北京')
+
+const scenes = [
+  { id: 'delivery', name: '外卖点餐', icon: '🍔' },
+  { id: 'wechat', name: '微信登录', icon: '💬' },
+  { id: 'weather', name: '天气查询', icon: '🌤️' }
+]
+
+function getSceneData() {
+  const sceneMap = {
+    delivery: {
+      appTitle: '外卖 APP',
+      apiIcon: '🛵',
+      serverName: '餐厅系统',
+      requestData: '订单: 汉堡+薯条'
+    },
+    wechat: {
+      appTitle: '第三方 APP',
+      apiIcon: '🔐',
+      serverName: '微信服务器',
+      requestData: '验证用户身份'
+    },
+    weather: {
+      appTitle: '天气 APP',
+      apiIcon: '📡',
+      serverName: '气象局数据',
+      requestData: `查询: ${searchCity.value}天气`
+    }
+  }
+  return sceneMap[currentScene.value]
+}
+
+async function placeOrder() {
+  if (isProcessing.value) return
+  await processRequest({
+    status: 'success',
+    message: '下单成功',
+    data: {
+      orderId: 'DD20240115001',
+      estimatedTime: '30分钟',
+      items: [
+        { name: '牛肉汉堡', quantity: 1, price: 35 },
+        { name: '薯条', quantity: 1, price: 12 }
+      ],
+      total: 47
+    }
+  })
+}
+
+async function wechatLogin() {
+  if (isProcessing.value) return
+  await processRequest({
+    status: 'success',
+    message: '登录成功',
+    data: {
+      userId: 'wx_123456',
+      nickname: '微信用户',
+      avatar: 'https://example.com/avatar.jpg'
+    }
+  })
+}
+
+async function searchWeather() {
+  if (isProcessing.value || !searchCity.value) return
+  await processRequest({
+    status: 'success',
+    message: '查询成功',
+    data: {
+      city: searchCity.value,
+      temperature: '22°C',
+      weather: '晴',
+      humidity: '45%',
+      wind: '东南风 3级'
+    }
+  })
+}
+
+async function processRequest(mockResponse) {
+  isProcessing.value = true
+  response.value = null
+
+  // 步骤1: 发起请求
+  currentStep.value = 1
+  await sleep(600)
+
+  // 步骤2: API 传递
+  currentStep.value = 2
+  await sleep(800)
+
+  // 步骤3: 服务器处理
+  currentStep.value = 3
+  await sleep(1000)
+
+  // 步骤4: 返回结果
+  currentStep.value = 4
+  response.value = mockResponse
+  await sleep(500)
+
+  isProcessing.value = false
+}
+
+function switchScene(sceneId) {
+  currentScene.value = sceneId
+  currentStep.value = 0
+  response.value = null
+  searchCity.value = '北京'
+}
+
+function formatResponse(resp) {
+  return JSON.stringify(resp, null, 2)
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+</script>
+
+<style scoped>
+.api-quick-start-demo {
+  border: 2px solid #e0e0e0;
+  border-radius: 16px;
+  padding: 32px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 32px;
+}
+
+.demo-header h2 {
+  font-size: 32px;
+  margin: 0 0 12px 0;
+  color: white;
+}
+
+.subtitle {
+  font-size: 16px;
+  opacity: 0.9;
+  margin: 0;
+}
+
+.scene-selector {
+  display: flex;
+  justify-content: center;
+  gap: 12px;
+  margin-bottom: 32px;
+}
+
+.scene-btn {
+  padding: 12px 24px;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.1);
+  color: white;
+  cursor: pointer;
+  font-size: 15px;
+  transition: all 0.3s;
+}
+
+.scene-btn:hover {
+  background: rgba(255, 255, 255, 0.2);
+}
+
+.scene-btn.active {
+  background: white;
+  color: #667eea;
+  border-color: white;
+}
+
+.demo-stage {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 24px;
+  margin-bottom: 32px;
+}
+
+.client-zone,
+.api-zone,
+.server-zone {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.phone-frame {
+  width: 180px;
+  height: 320px;
+  background: #1a1a1a;
+  border-radius: 24px;
+  padding: 12px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+}
+
+.phone-screen {
+  width: 100%;
+  height: 100%;
+  background: white;
+  border-radius: 16px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.app-header {
+  background: #667eea;
+  color: white;
+  padding: 12px;
+  text-align: center;
+  font-size: 13px;
+  font-weight: bold;
+}
+
+.app-content {
+  flex: 1;
+  padding: 12px;
+  overflow-y: auto;
+  color: #333;
+}
+
+.restaurant-info {
+  margin-bottom: 16px;
+}
+
+.restaurant-name {
+  font-weight: bold;
+  margin-bottom: 12px;
+  color: #333;
+}
+
+.dish-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.dish-item {
+  display: flex;
+  justify-content: space-between;
+  padding: 8px;
+  background: #f8f9fa;
+  border-radius: 6px;
+  font-size: 12px;
+}
+
+.order-btn,
+.login-btn,
+.search-btn {
+  width: 100%;
+  padding: 12px;
+  background: #667eea;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-size: 14px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.order-btn:disabled,
+.login-btn:disabled,
+.search-btn:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.login-logo {
+  font-size: 48px;
+  text-align: center;
+  margin-bottom: 12px;
+}
+
+.login-title {
+  text-align: center;
+  margin-bottom: 20px;
+  color: #333;
+  font-size: 16px;
+}
+
+.wechat-icon {
+  margin-right: 6px;
+}
+
+.weather-search {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.search-input {
+  padding: 8px;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  font-size: 13px;
+}
+
+.api-container {
+  width: 120px;
+  height: 120px;
+  background: rgba(255, 255, 255, 0.2);
+  border-radius: 50%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+}
+
+.api-icon {
+  font-size: 48px;
+  transition: transform 0.3s;
+}
+
+.api-icon.moving {
+  animation: deliveryMove 1.5s ease-in-out infinite;
+}
+
+@keyframes deliveryMove {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+  50% {
+    transform: translateX(20px);
+  }
+}
+
+.api-label {
+  margin-top: 8px;
+  font-size: 14px;
+  font-weight: bold;
+}
+
+.data-flow {
+  position: absolute;
+  top: -20px;
+  background: white;
+  color: #333;
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-size: 11px;
+  white-space: nowrap;
+  animation: floatData 1s infinite;
+}
+
+@keyframes floatData {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-5px);
+  }
+}
+
+.server-container {
+  width: 200px;
+  background: rgba(255, 255, 255, 0.15);
+  border-radius: 12px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-height: 120px;
+}
+
+.server-icon {
+  font-size: 48px;
+  margin-bottom: 8px;
+}
+
+.server-label {
+  font-size: 13px;
+  font-weight: bold;
+}
+
+.processing-indicator {
+  margin-top: 12px;
+  text-align: center;
+}
+
+.dots {
+  display: flex;
+  gap: 4px;
+  justify-content: center;
+}
+
+.dots span {
+  width: 8px;
+  height: 8px;
+  background: white;
+  border-radius: 50%;
+  animation: bounce 1.4s infinite ease-in-out both;
+}
+
+.dots span:nth-child(1) {
+  animation-delay: -0.32s;
+}
+.dots span:nth-child(2) {
+  animation-delay: -0.16s;
+}
+
+@keyframes bounce {
+  0%,
+  80%,
+  100% {
+    transform: scale(0);
+  }
+  40% {
+    transform: scale(1);
+  }
+}
+
+.processing-text {
+  margin-top: 8px;
+  font-size: 12px;
+}
+
+.result-display {
+  margin-top: 12px;
+  width: 100%;
+}
+
+.result-label {
+  font-size: 11px;
+  margin-bottom: 6px;
+  opacity: 0.8;
+}
+
+.result-data {
+  background: rgba(0, 0, 0, 0.3);
+  color: #4ade80;
+  padding: 8px;
+  border-radius: 6px;
+  font-size: 10px;
+  margin: 0;
+  overflow-x: auto;
+}
+
+.zone-label {
+  margin-top: 12px;
+  font-size: 13px;
+  opacity: 0.9;
+}
+
+.flow-explanation {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 24px;
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 12px;
+  margin-bottom: 24px;
+}
+
+.step {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  opacity: 0.5;
+  transition: all 0.3s;
+}
+
+.step.active {
+  opacity: 1;
+}
+
+.step-number {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.2);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: bold;
+  font-size: 18px;
+}
+
+.step.active .step-number {
+  background: white;
+  color: #667eea;
+}
+
+.step-text {
+  font-size: 12px;
+}
+
+.arrow {
+  font-size: 24px;
+  opacity: 0.5;
+}
+
+.key-points {
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 12px;
+  padding: 24px;
+}
+
+.key-points h4 {
+  margin: 0 0 20px 0;
+  text-align: center;
+  font-size: 18px;
+}
+
+.points-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 16px;
+}
+
+.point-card {
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 8px;
+  padding: 16px;
+  text-align: center;
+}
+
+.point-icon {
+  font-size: 36px;
+  margin-bottom: 8px;
+}
+
+.point-title {
+  font-weight: bold;
+  margin-bottom: 6px;
+}
+
+.point-desc {
+  font-size: 13px;
+  opacity: 0.9;
+  line-height: 1.5;
+}
+
+@media (max-width: 768px) {
+  .demo-stage {
+    grid-template-columns: 1fr;
+  }
+
+  .flow-explanation {
+    flex-wrap: wrap;
+  }
+
+  .api-quick-start-demo {
+    padding: 16px;
+  }
+
+  .demo-header h2 {
+    font-size: 24px;
+  }
+
+  .points-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/RequestResponseFlow.vue b/docs/.vitepress/theme/components/appendix/api-intro/RequestResponseFlow.vue
new file mode 100644
index 0000000..d5748fa
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/api-intro/RequestResponseFlow.vue
@@ -0,0 +1,452 @@
+<template>
+  <div class="request-response-flow">
+    <div class="demo-header">
+      <h3>📡 API 请求-响应流程</h3>
+      <p>观察一个完整的 API 调用过程</p>
+    </div>
+
+    <!-- 请求配置 -->
+    <div class="request-config">
+      <label>
+        请求方法：
+        <select v-model="requestMethod">
+          <option value="GET">GET</option>
+          <option value="POST">POST</option>
+          <option value="PUT">PUT</option>
+          <option value="DELETE">DELETE</option>
+        </select>
+      </label>
+
+      <label>
+        接口地址：
+        <input v-model="requestUrl" placeholder="/api/users" />
+      </label>
+
+      <button @click="sendRequest" :disabled="isLoading">
+        {{ isLoading ? '发送中...' : '🚀 发送请求' }}
+      </button>
+    </div>
+
+    <!-- 流程可视化 -->
+    <div class="flow-visualization">
+      <div
+        class="flow-step"
+        v-for="(step, index) in steps"
+        :key="index"
+        :class="{
+          active: currentStep === index,
+          completed: currentStep > index
+        }"
+      >
+        <div class="step-number">{{ index + 1 }}</div>
+        <div class="step-content">
+          <div class="step-title">{{ step.title }}</div>
+          <div class="step-description">{{ step.description }}</div>
+          <div v-if="currentStep === index" class="step-detail">
+            {{ step.detail }}
+          </div>
+        </div>
+        <div v-if="index < steps.length - 1" class="step-arrow">→</div>
+      </div>
+    </div>
+
+    <!-- 请求/响应详情 -->
+    <div class="details-panel">
+      <div class="request-detail">
+        <h4>📤 请求详情</h4>
+        <pre><code>{{ requestDetail }}</code></pre>
+      </div>
+
+      <div class="response-detail">
+        <h4>📥 响应详情</h4>
+        <div v-if="responseData">
+          <div class="status-badge" :class="responseStatusClass">
+            {{ responseData.status }} {{ responseData.statusText }}
+          </div>
+          <pre><code>{{ JSON.stringify(responseData.data, null, 2) }}</code></pre>
+          <div class="response-meta">
+            <span>⏱️ 耗时: {{ responseTime }}ms</span>
+            <span>📦 大小: {{ responseSize }} bytes</span>
+          </div>
+        </div>
+        <div v-else class="waiting">等待请求...</div>
+      </div>
+    </div>
+
+    <!-- 状态码说明 -->
+    <div class="status-codes">
+      <h4>常见状态码</h4>
+      <div class="code-list">
+        <span class="code success">200 - 成功</span>
+        <span class="code redirect">301 - 重定向</span>
+        <span class="code client-error">400 - 客户端错误</span>
+        <span class="code client-error">401 - 未授权</span>
+        <span class="code client-error">404 - 未找到</span>
+        <span class="code server-error">500 - 服务器错误</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const requestMethod = ref('GET')
+const requestUrl = ref('/api/users')
+const isLoading = ref(false)
+const currentStep = ref(-1)
+const responseData = ref(null)
+const responseTime = ref(0)
+const responseSize = ref(0)
+
+const steps = [
+  {
+    title: '客户端发起请求',
+    description: '浏览器/APP 构建请求',
+    get detail() {
+      return `${requestMethod.value} ${requestUrl.value}`
+    }
+  },
+  {
+    title: '网络传输',
+    description: '请求通过互联网发送',
+    get detail() {
+      return 'TCP/IP 数据包传输中...'
+    }
+  },
+  {
+    title: '服务器接收并处理',
+    description: '解析请求，查询数据库/执行逻辑',
+    get detail() {
+      return `处理 ${requestMethod.value} 请求...`
+    }
+  },
+  {
+    title: '服务器返回响应',
+    description: '生成 JSON 数据并返回',
+    get detail() {
+      return 'HTTP/1.1 200 OK'
+    }
+  },
+  {
+    title: '客户端接收响应',
+    description: '解析数据并更新界面',
+    get detail() {
+      return '接收数据，渲染页面'
+    }
+  }
+]
+
+const requestDetail = computed(() => {
+  return `${requestMethod.value} ${requestUrl.value} HTTP/1.1
+Host: api.example.com
+Content-Type: application/json
+
+${
+  requestMethod.value !== 'GET'
+    ? '{\n  "name": "张三",\n  "email": "zhangsan@example.com"\n}'
+    : ''
+}`
+})
+
+const responseStatusClass = computed(() => {
+  if (!responseData.value) return ''
+  const status = responseData.value.status
+  if (status >= 200 && status < 300) return 'success'
+  if (status >= 300 && status < 400) return 'redirect'
+  if (status >= 400 && status < 500) return 'client-error'
+  if (status >= 500) return 'server-error'
+  return ''
+})
+
+async function sendRequest() {
+  if (isLoading.value) return
+
+  isLoading.value = true
+  responseData.value = null
+  currentStep.value = -1
+
+  // 模拟请求流程
+  for (let i = 0; i < steps.length; i++) {
+    currentStep.value = i
+    await sleep(800)
+  }
+
+  // 模拟响应数据
+  const startTime = Date.now()
+  responseTime.value = Math.floor(Math.random() * 200) + 50
+  responseSize.value = Math.floor(Math.random() * 1000) + 100
+
+  responseData.value = {
+    status: 200,
+    statusText: 'OK',
+    data: {
+      id: 1,
+      name: '张三',
+      email: 'zhangsan@example.com',
+      createdAt: '2024-01-01T00:00:00Z'
+    }
+  }
+
+  await sleep(responseTime.value)
+
+  isLoading.value = false
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+</script>
+
+<style scoped>
+.request-response-flow {
+  border: 2px solid #e0e0e0;
+  border-radius: 12px;
+  padding: 24px;
+  background: #fafafa;
+}
+
+.demo-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.demo-header h3 {
+  font-size: 20px;
+  margin: 0 0 8px 0;
+  color: #2c3e50;
+}
+
+.request-config {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  padding: 16px;
+  background: white;
+  border-radius: 8px;
+  margin-bottom: 24px;
+  flex-wrap: wrap;
+}
+
+.request-config label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.request-config select,
+.request-config input {
+  padding: 8px 12px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.request-config button {
+  padding: 8px 16px;
+  background: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.request-config button:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.flow-visualization {
+  background: white;
+  border-radius: 8px;
+  padding: 24px;
+  margin-bottom: 24px;
+}
+
+.flow-step {
+  display: flex;
+  align-items: flex-start;
+  gap: 16px;
+  position: relative;
+  padding: 12px 0;
+}
+
+.step-number {
+  width: 36px;
+  height: 36px;
+  border-radius: 50%;
+  background: #e0e0e0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: bold;
+  flex-shrink: 0;
+}
+
+.flow-step.active .step-number {
+  background: #007bff;
+  color: white;
+  animation: pulse 1s infinite;
+}
+
+.flow-step.completed .step-number {
+  background: #28a745;
+  color: white;
+}
+
+.step-content {
+  flex: 1;
+}
+
+.step-title {
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.step-description {
+  color: #666;
+  font-size: 14px;
+}
+
+.step-detail {
+  margin-top: 8px;
+  padding: 8px;
+  background: #f8f9fa;
+  border-radius: 4px;
+  font-family: monospace;
+  font-size: 13px;
+  color: #007bff;
+}
+
+.step-arrow {
+  font-size: 24px;
+  color: #ccc;
+  margin-left: 16px;
+}
+
+.flow-step.active .step-arrow {
+  color: #007bff;
+  animation: arrowMove 1s infinite;
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.1);
+  }
+}
+
+@keyframes arrowMove {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+  50% {
+    transform: translateX(5px);
+  }
+}
+
+.details-panel {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.request-detail,
+.response-detail {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.request-detail h4,
+.response-detail h4 {
+  margin: 0 0 12px 0;
+  font-size: 16px;
+}
+
+.request-detail pre,
+.response-detail pre {
+  background: #f8f9fa;
+  padding: 12px;
+  border-radius: 4px;
+  overflow-x: auto;
+  font-size: 13px;
+  margin: 0;
+}
+
+.status-badge {
+  display: inline-block;
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-weight: bold;
+  margin-bottom: 12px;
+}
+
+.status-badge.success {
+  background: #d4edda;
+  color: #155724;
+}
+
+.response-meta {
+  margin-top: 12px;
+  font-size: 13px;
+  color: #666;
+  display: flex;
+  gap: 16px;
+}
+
+.waiting {
+  color: #999;
+  font-style: italic;
+}
+
+.status-codes {
+  background: white;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.status-codes h4 {
+  margin: 0 0 12px 0;
+  font-size: 16px;
+}
+
+.code-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.code {
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-size: 13px;
+  font-family: monospace;
+}
+
+.code.success {
+  background: #d4edda;
+  color: #155724;
+}
+
+.code.redirect {
+  background: #fff3cd;
+  color: #856404;
+}
+
+.code.client-error {
+  background: #f8d7da;
+  color: #721c24;
+}
+
+.code.server-error {
+  background: #f5c6cb;
+  color: #721c24;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/AuthBasicsDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/AuthBasicsDemo.vue
index 1698efe..7612d14 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/AuthBasicsDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/AuthBasicsDemo.vue
@@ -1,457 +1,266 @@
 <!--
   AuthBasicsDemo.vue
-  鉴权基础概念演示
+  鉴权基础：你到底在“传什么”来证明身份？
 -->
 <template>
   <div class="auth-basics-demo">
     <div class="header">
-      <div class="title">为什么要鉴权？</div>
-      <div class="subtitle">理解系统安全的第一道防线</div>
+      <div class="title">🧰 鉴权的 4 种常见“凭证”</div>
+      <div class="subtitle">
+        选一个方案，看看请求长什么样、优缺点是什么、最常见坑是什么。
+      </div>
     </div>
 
-    <div class="building-metaphor">
-      <div class="building">
-        <div class="building-header">
-          <div class="building-icon">🏢</div>
-          <div class="building-text">后端系统 = 一栋大楼</div>
-        </div>
+    <div class="tabs">
+      <button
+        v-for="m in methods"
+        :key="m.id"
+        class="tab"
+        :class="{ active: current === m.id }"
+        @click="current = m.id"
+      >
+        {{ m.name }}
+        <span class="tag">{{ m.bestFor }}</span>
+      </button>
+    </div>
 
-        <div class="building-areas">
-          <div
-            v-for="area in areas"
-            :key="area.key"
-            class="area"
-            :class="{
-              protected: area.protected,
-              'can-access': canAccess(area)
-            }"
-            @click="toggleProtection(area)"
-          >
-            <div class="area-icon">{{ area.icon }}</div>
-            <div class="area-label">{{ area.label }}</div>
-            <div class="area-status" v-if="area.protected">
-              <div class="lock-icon">🔒</div>
-              <div class="lock-text">需要{{ area.requiredRole }}</div>
-            </div>
-            <div class="area-access" v-if="canAccess(area)">
-              <div class="access-icon">✅</div>
-              <div class="access-text">可访问</div>
-            </div>
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">请求长什么样</div>
+        <pre class="code"><code>{{ active.example }}</code></pre>
+        <div class="hint">{{ active.note }}</div>
+      </div>
+
+      <div class="card">
+        <div class="card-title">什么时候用 / 不用</div>
+        <div class="two">
+          <div class="box">
+            <div class="box-title">✅ 适合</div>
+            <ul class="list">
+              <li v-for="(x, i) in active.pros" :key="i">{{ x }}</li>
+            </ul>
+          </div>
+          <div class="box">
+            <div class="box-title">⚠️ 不适合 / 风险</div>
+            <ul class="list">
+              <li v-for="(x, i) in active.cons" :key="i">{{ x }}</li>
+            </ul>
           </div>
         </div>
       </div>
     </div>
 
-    <div class="user-control">
-      <div class="control-title">当前用户角色</div>
-      <div class="role-selector">
-        <button
-          v-for="role in roles"
-          :key="role.key"
-          class="role-btn"
-          :class="{ active: currentRole === role.key }"
-          @click="setRole(role.key)"
-        >
-          <span class="role-icon">{{ role.icon }}</span>
-          <span class="role-name">{{ role.name }}</span>
-        </button>
-      </div>
-    </div>
-
-    <div class="scenarios">
-      <div class="section-title">保护资源的理由</div>
-      <div class="scenario-cards">
-        <div
-          v-for="scenario in scenarios"
-          :key="scenario.key"
-          class="scenario-card"
-          :class="`scenario-${scenario.key}`"
-        >
-          <div class="scenario-icon">{{ scenario.icon }}</div>
-          <div class="scenario-title">{{ scenario.title }}</div>
-          <div class="scenario-desc">{{ scenario.description }}</div>
-          <div class="scenario-example">{{ scenario.example }}</div>
-        </div>
-      </div>
-    </div>
-
-    <div class="key-point">
-      <div class="key-point-icon">💡</div>
-      <div class="key-point-text">
-        <strong>关键点：</strong
-        >鉴权是第一道防线，所有敏感操作都必须先验证身份。
-        没有鉴权的系统就像没有门禁的大楼，任何人都可以进出。
+    <div class="card">
+      <div class="card-title">一句话口诀</div>
+      <div class="desc">
+        <strong>先认证（你是谁）</strong
+        >，再授权（你能做什么）。凭证只是“证明身份的方式”，授权永远要在服务端执行。
       </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const currentRole = ref('guest')
+const methods = [
+  {
+    id: 'basic',
+    name: 'HTTP Basic',
+    bestFor: '内部工具',
+    example: `GET /api/profile
+Authorization: Basic <base64(username:password)>`,
+    note: 'Base64 不是加密；必须配合 HTTPS，且不建议用于公网生产。',
+    pros: ['最简单，所有客户端都支持', '适合内部/临时调试工具'],
+    cons: [
+      '每次请求都带密码（风险大）',
+      '无法“注销”（除非服务端改密码）',
+      '不适合现代业务'
+    ]
+  },
+  {
+    id: 'cookie',
+    name: 'Session + Cookie',
+    bestFor: '传统 Web',
+    example: `POST /login
+→ 200 OK
+Set-Cookie: session_id=abc; HttpOnly; Secure; SameSite=Lax
 
-const roles = [
-  { key: 'guest', name: '访客', icon: '👤' },
-  { key: 'user', name: '普通用户', icon: '👤' },
-  { key: 'vip', name: 'VIP 用户', icon: '⭐' },
-  { key: 'admin', name: '管理员', icon: '👨‍💼' }
-]
+GET /api/profile
+Cookie: session_id=abc`,
+    note: '浏览器会自动带 Cookie；因此一定要做 CSRF 防护（SameSite / CSRF Token）。',
+    pros: ['服务端可控（可主动注销）', '适合 SSR/同域 Web', '实现直观'],
+    cons: ['服务端有状态（需要共享 session）', '跨域复杂', '容易被 CSRF 影响']
+  },
+  {
+    id: 'jwt',
+    name: 'JWT Bearer',
+    bestFor: 'API/移动端',
+    example: `POST /login
+→ { "access_token": "..." }
 
-const areas = ref([
-  {
-    key: 'lobby',
-    label: '大厅',
-    icon: '🚪',
-    protected: false,
-    requiredRole: null
+GET /api/profile
+Authorization: Bearer <access_token>`,
+    note: 'JWT payload 可解码；不要放敏感信息。建议短 access token + refresh token。',
+    pros: ['无状态，易扩展', '跨域友好', '移动端/多服务常用'],
+    cons: [
+      '难以全局注销（需要额外机制）',
+      'token 变大，每次都要带',
+      '设计不好会导致权限失控'
+    ]
   },
   {
-    key: 'profile',
-    label: '个人资料',
-    icon: '👤',
-    protected: true,
-    requiredRole: '登录'
-  },
-  {
-    key: 'vip-lounge',
-    label: 'VIP 休息室',
-    icon: '⭐',
-    protected: true,
-    requiredRole: 'VIP'
-  },
-  {
-    key: 'admin-room',
-    label: '管理员办公室',
-    icon: '👨‍💼',
-    protected: true,
-    requiredRole: '管理员'
-  }
-])
-
-const scenarios = [
-  {
-    key: 'privacy',
-    icon: '🔐',
-    title: '隐私保护',
-    description: '个人信息、聊天记录只能本人查看',
-    example: '你的微信聊天记录，别人不能看'
-  },
-  {
-    key: 'permission',
-    icon: '🛡️',
-    title: '权限控制',
-    description: '不同角色有不同的操作权限',
-    example: '管理员可以删除用户，普通用户不行'
-  },
-  {
-    key: 'abuse',
-    icon: '🚫',
-    title: '防止滥用',
-    description: '防止恶意调用、刷接口、爬虫',
-    example: '限制 API 调用频率，防止服务被攻击'
+    id: 'apikey',
+    name: 'API Key',
+    bestFor: '服务到服务',
+    example: `GET /api/metrics
+X-API-Key: <your_api_key>`,
+    note: 'API Key 更像“门禁卡”，要配合限流、IP 白名单、轮换、最小权限。',
+    pros: ['实现简单', '适合服务间/脚本访问', '易于轮换（如果设计得当）'],
+    cons: ['通常缺少用户上下文', '泄露后影响大', '需要做权限/轮换/审计']
   }
 ]
 
-const setRole = (role) => {
-  currentRole.value = role
-}
-
-const toggleProtection = (area) => {
-  area.protected = !area.protected
-}
-
-const canAccess = (area) => {
-  if (!area.protected) return true
-
-  const roleAccess = {
-    guest: [],
-    user: ['登录'],
-    vip: ['登录', 'VIP'],
-    admin: ['登录', 'VIP', '管理员']
-  }
-
-  const permissions = roleAccess[currentRole.value] || []
-  return permissions.includes(area.requiredRole)
-}
+const current = ref(methods[0].id)
+const active = computed(
+  () => methods.find((m) => m.id === current.value) || methods[0]
+)
 </script>
 
 <style scoped>
 .auth-basics-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
-.building-metaphor {
-  margin-bottom: 1.5rem;
-}
-
-.building {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.building-header {
+.tabs {
   display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  margin-bottom: 1rem;
-  padding-bottom: 1rem;
-  border-bottom: 1px solid var(--vp-c-divider);
-}
-
-.building-icon {
-  font-size: 2rem;
-}
-
-.building-text {
-  font-size: 1.05rem;
-  font-weight: 600;
-}
-
-.building-areas {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
-  gap: 0.75rem;
-}
-
-.area {
-  position: relative;
-  background: var(--vp-c-bg-soft);
-  border: 2px solid var(--vp-c-divider);
-  border-radius: 10px;
-  padding: 1rem;
-  text-align: center;
-  cursor: pointer;
-  transition: all 0.2s ease;
-}
-
-.area:hover {
-  border-color: var(--vp-c-brand);
-  transform: translateY(-2px);
-}
-
-.area.protected {
-  border-color: #f59e0b;
-  background: rgba(245, 158, 11, 0.05);
-}
-
-.area.can-access {
-  border-color: #22c55e;
-  background: rgba(34, 197, 94, 0.05);
-}
-
-.area-icon {
-  font-size: 2rem;
-  margin-bottom: 0.5rem;
-}
-
-.area-label {
-  font-weight: 600;
-  font-size: 0.9rem;
-  margin-bottom: 0.5rem;
-}
-
-.area-status,
-.area-access {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.25rem;
-  font-size: 0.75rem;
-  margin-top: 0.5rem;
-}
-
-.lock-icon,
-.access-icon {
-  font-size: 1rem;
-}
-
-.lock-text {
-  color: #f59e0b;
-  font-weight: 600;
-}
-
-.access-text {
-  color: #22c55e;
-  font-weight: 600;
-}
-
-.user-control {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.control-title {
-  font-weight: 600;
-  margin-bottom: 0.75rem;
-  font-size: 0.95rem;
-}
-
-.role-selector {
-  display: flex;
-  gap: 0.5rem;
   flex-wrap: wrap;
-}
-
-.role-btn {
-  flex: 1;
-  min-width: 100px;
-  padding: 0.75rem;
-  border: 2px solid var(--vp-c-divider);
-  border-radius: 8px;
-  background: var(--vp-c-bg-soft);
-  cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
-  align-items: center;
-  justify-content: center;
   gap: 0.5rem;
-  font-size: 0.9rem;
-}
-
-.role-btn:hover {
-  border-color: var(--vp-c-brand);
-}
-
-.role-btn.active {
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-}
-
-.role-icon {
-  font-size: 1.2rem;
-}
-
-.scenarios {
-  margin-bottom: 1.5rem;
-}
-
-.section-title {
-  font-weight: 600;
   margin-bottom: 1rem;
-  font-size: 1rem;
 }
 
-.scenario-cards {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-  gap: 1rem;
-}
-
-.scenario-card {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
+.tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: 999px;
   border: 1px solid var(--vp-c-divider);
-  transition: all 0.2s ease;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
 }
 
-.scenario-card:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+.tab.active {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
 }
 
-.scenario-icon {
-  font-size: 2rem;
-  margin-bottom: 0.75rem;
-}
-
-.scenario-title {
-  font-weight: 600;
-  font-size: 0.95rem;
-  margin-bottom: 0.5rem;
-}
-
-.scenario-desc {
-  font-size: 0.85rem;
-  color: var(--vp-c-text-2);
-  margin-bottom: 0.5rem;
-  line-height: 1.5;
-}
-
-.scenario-example {
-  font-size: 0.8rem;
-  color: var(--vp-c-text-2);
-  font-style: italic;
-  padding: 0.5rem;
+.tag {
+  font-size: 0.75rem;
+  padding: 0.15rem 0.5rem;
+  border-radius: 999px;
+  border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 6px;
-  border-left: 3px solid var(--vp-c-brand);
+  color: var(--vp-c-text-2);
+  font-weight: 600;
 }
 
-.scenario-privacy .scenario-icon {
-  filter: hue-rotate(200deg);
-}
-.scenario-permission .scenario-icon {
-  filter: hue-rotate(120deg);
-}
-.scenario-abuse .scenario-icon {
-  filter: hue-rotate(0deg);
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin-bottom: 1rem;
 }
 
-.key-point {
-  display: flex;
-  gap: 0.75rem;
-  background: rgba(59, 130, 246, 0.1);
-  border-left: 4px solid var(--vp-c-brand);
-  padding: 1rem;
+.card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
+  padding: 1rem;
 }
 
-.key-point-icon {
-  font-size: 1.5rem;
-  flex-shrink: 0;
+.card-title {
+  font-weight: 800;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
 }
 
-.key-point-text {
+.code {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+}
+
+.hint {
+  margin-top: 0.75rem;
+  color: var(--vp-c-text-2);
   font-size: 0.9rem;
-  line-height: 1.6;
+  line-height: 1.7;
 }
 
-.key-point-text strong {
-  color: var(--vp-c-brand);
+.two {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.75rem;
 }
 
-@media (max-width: 768px) {
-  .building-areas {
-    grid-template-columns: repeat(2, 1fr);
-  }
+.box {
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
 
-  .scenario-cards {
+.box-title {
+  font-weight: 800;
+  margin-bottom: 0.5rem;
+  color: var(--vp-c-text-1);
+}
+
+.list {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+.desc {
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+@media (max-width: 720px) {
+  .grid {
     grid-template-columns: 1fr;
   }
-
-  .role-selector {
-    flex-direction: column;
-  }
-
-  .role-btn {
-    min-width: auto;
+  .two {
+    grid-template-columns: 1fr;
   }
 }
 </style>
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/AuthEvolutionDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/AuthEvolutionDemo.vue
index 8370596..8675101 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/AuthEvolutionDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/AuthEvolutionDemo.vue
@@ -1,415 +1,256 @@
 <!--
   AuthEvolutionDemo.vue
-  鉴权方案演进史演示
+  鉴权方案演进（更可用：给出“什么时候用”）
 -->
 <template>
   <div class="auth-evolution-demo">
     <div class="header">
-      <div class="title">鉴权方案演进史</div>
-      <div class="subtitle">从 HTTP Basic 到现代 JWT 的技术演进</div>
+      <div class="title">🧭 鉴权方案演进：从 Basic 到 OAuth2</div>
+      <div class="subtitle">点击卡片，快速建立“场景 → 方案”的直觉。</div>
     </div>
 
     <div class="timeline">
-      <div
-        v-for="(era, index) in eras"
-        :key="era.key"
-        class="era-item"
-        :class="{ active: selectedEra === era.key }"
-        @click="selectEra(era.key)"
+      <button
+        v-for="s in stages"
+        :key="s.id"
+        class="stage"
+        :class="{ active: activeId === s.id }"
+        @click="activeId = s.id"
       >
-        <div class="era-marker">{{ index + 1 }}</div>
-        <div class="era-content">
-          <div class="era-title">{{ era.title }}</div>
-          <div class="era-year">{{ era.year }}</div>
+        <div class="stage-top">
+          <span class="icon">{{ s.icon }}</span>
+          <span class="name">{{ s.name }}</span>
         </div>
-      </div>
+        <div class="stage-sub">{{ s.when }}</div>
+      </button>
     </div>
 
-    <div class="era-details" v-if="currentEra">
-      <div class="era-header">
-        <h3>{{ currentEra.title }}</h3>
-        <span class="era-badge">{{ currentEra.year }}</span>
-      </div>
+    <div class="card">
+      <div class="card-title">{{ active.icon }} {{ active.name }}</div>
+      <div class="desc">{{ active.desc }}</div>
 
-      <div class="era-description">
-        {{ currentEra.description }}
-      </div>
-
-      <div class="era-flow" v-if="currentEra.flow">
-        <div class="flow-title">工作流程</div>
-        <div class="flow-steps">
-          <div
-            v-for="(step, idx) in currentEra.flow"
-            :key="idx"
-            class="flow-step"
-          >
-            <div class="step-number">{{ idx + 1 }}</div>
-            <div class="step-content">{{ step }}</div>
-            <div v-if="idx < currentEra.flow.length - 1" class="step-arrow">
-              →
-            </div>
-          </div>
-        </div>
-      </div>
-
-      <div class="era-pros-cons">
-        <div class="pros">
-          <div class="list-title">优点</div>
-          <ul>
-            <li v-for="(pro, idx) in currentEra.pros" :key="idx">{{ pro }}</li>
+      <div class="grid">
+        <div class="box">
+          <div class="box-title">✅ 适合</div>
+          <ul class="list">
+            <li v-for="(x, i) in active.pros" :key="i">{{ x }}</li>
           </ul>
         </div>
-        <div class="cons">
-          <div class="list-title">缺点</div>
-          <ul>
-            <li v-for="(con, idx) in currentEra.cons" :key="idx">{{ con }}</li>
+        <div class="box">
+          <div class="box-title">⚠️ 主要风险</div>
+          <ul class="list">
+            <li v-for="(x, i) in active.cons" :key="i">{{ x }}</li>
           </ul>
         </div>
       </div>
 
-      <div class="era-usecase">
-        <div class="usecase-title">适用场景</div>
-        <div class="usecase-content">{{ currentEra.usecase }}</div>
-      </div>
+      <pre class="code"><code>{{ active.example }}</code></pre>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const selectedEra = ref('basic')
-
-const eras = [
+const stages = [
   {
-    key: 'basic',
-    title: 'HTTP Basic Authentication',
-    year: '1990s',
-    description:
-      '最古老的鉴权方案，直接把用户名密码经过 Base64 编码后放在 HTTP 头中。虽然简单，但因为安全性问题已不推荐使用。',
-    flow: [
-      '客户端发送用户名密码',
-      '服务器验证身份',
-      '返回受保护资源',
-      '每次请求都携带密码'
-    ],
-    pros: ['实现简单，所有浏览器都支持', '标准化协议', '无需额外存储'],
-    cons: [
-      'Base64 可解码，相当于明文传输',
-      '每次请求都要传密码，容易被截获',
-      '无法主动注销（除非关闭浏览器）',
-      '无法防止 CSRF 攻击'
-    ],
-    usecase: '只适合内部测试工具，绝不用于生产环境'
+    id: 'basic',
+    icon: '🪪',
+    name: 'HTTP Basic',
+    when: '内部工具/调试',
+    desc: '最早期的方案：每次请求都带 username/password（或等价凭证）。',
+    pros: ['实现最简单', '不需要额外存储'],
+    cons: ['每次请求都带“高价值凭证”', '不适合公网生产', '很难做细粒度授权'],
+    example: `GET /api/profile
+Authorization: Basic <base64(username:password)>`
   },
   {
-    key: 'session',
-    title: 'Session + Cookie',
-    year: '2000s',
-    description:
-      'Web 开发的经典方案。服务器验证用户身份后创建 Session，返回 Session ID 给客户端，客户端每次请求自动带上 Cookie。',
-    flow: [
-      '用户登录提交用户名密码',
-      '服务器验证并创建 Session',
-      '返回 Set-Cookie: session_id',
-      '后续请求自动带上 Cookie'
-    ],
-    pros: [
-      '简单直观，易于理解',
-      '服务端可以主动注销（删除 Session）',
-      'Session 信息存储在服务端，相对安全'
-    ],
+    id: 'session',
+    icon: '🍪',
+    name: 'Session + Cookie',
+    when: '传统 Web / SSR',
+    desc: '服务端存 Session，浏览器存 cookie(session_id)。后续请求自动带 Cookie。',
+    pros: ['服务端可主动注销', '很适合同域 SSR', '工程落地成熟'],
     cons: [
-      '服务器有状态，需要存储 Session',
-      '多台服务器需要共享 Session（如 Redis）',
-      '跨域困难，Cookie 默认不能跨域',
-      '容易受到 CSRF 攻击'
+      '服务端有状态，需要共享/扩展',
+      'CSRF 风险更高（必须防）',
+      '跨域更麻烦'
     ],
-    usecase: '适合传统 Web 应用（服务器端渲染），不适合移动端和现代 SPA'
+    example: `POST /login
+→ Set-Cookie: session_id=abc; HttpOnly; Secure; SameSite=Lax
+
+GET /api/profile
+Cookie: session_id=abc`
   },
   {
-    key: 'jwt',
-    title: 'JWT (JSON Web Token)',
-    year: '2010s',
-    description:
-      '现代 Web 的主流方案。不在服务端存储状态，把用户信息加密成 Token，放在客户端。JWT 由 Header、Payload、Signature 三部分组成。',
-    flow: [
-      '用户登录验证身份',
-      '服务器生成 JWT Token',
-      '客户端存储 Token（localStorage）',
-      '后续请求在 Header 中携带 Token'
+    id: 'jwt',
+    icon: '🎫',
+    name: 'JWT Access Token',
+    when: 'API / 移动端 / 多服务',
+    desc: '服务端不存状态，把声明编码为 token；请求携带 Authorization: Bearer。',
+    pros: ['无状态易扩展', '跨域友好', '多服务常用'],
+    cons: [
+      '难以全局注销（要额外机制）',
+      'token 体积大',
+      'payload 可读（别放敏感信息）'
     ],
+    example: `GET /api/profile
+Authorization: Bearer <access_token>`
+  },
+  {
+    id: 'oauth2',
+    icon: '🔑',
+    name: 'OAuth2 / OIDC',
+    when: '第三方登录/授权',
+    desc: '解决“第三方授权/登录”，让应用无需保存第三方账号密码。',
     pros: [
-      '无状态，服务端不存储 Session',
-      '易于横向扩展',
-      '跨域友好，不受 Cookie 限制',
-      '移动端友好，原生 App 也能轻松使用',
-      'Payload 可以存储用户信息、权限等'
+      '用户体验好（扫码/一键登录）',
+      '安全边界更清晰',
+      '可扩展到 OIDC（登录）'
     ],
     cons: [
-      '无法主动注销，Token 一旦签发在过期前一直有效',
-      'Payload 可见（Base64 编码），不能存敏感信息',
-      'Token 过大，每次请求都要带上',
-      '需要额外的黑名单机制实现注销'
+      '接入复杂度更高',
+      '必须正确处理 redirect_uri/state',
+      'token 生命周期设计很关键'
     ],
-    usecase: '现代 Web 和移动端的标准方案，特别适合分布式系统和微服务架构'
+    example: `GET /authorize?response_type=code&client_id=...&redirect_uri=...&state=...`
   }
 ]
 
-const currentEra = computed(() => eras.find((e) => e.key === selectedEra.value))
-
-const selectEra = (key) => {
-  selectedEra.value = key
-}
+const activeId = ref(stages[1].id)
+const active = computed(
+  () => stages.find((s) => s.id === activeId.value) || stages[0]
+)
 </script>
 
 <style scoped>
 .auth-evolution-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
 .timeline {
-  display: flex;
-  gap: 1rem;
-  margin-bottom: 1.5rem;
-  overflow-x: auto;
-  padding-bottom: 0.5rem;
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 0.75rem;
+  margin: 1rem 0;
 }
 
-.era-item {
-  flex: 1;
-  min-width: 180px;
-  padding: 1rem;
+.stage {
+  text-align: left;
+  padding: 0.75rem;
+  border-radius: 8px;
   border: 1px solid var(--vp-c-divider);
-  border-radius: 10px;
   background: var(--vp-c-bg);
   cursor: pointer;
-  transition: all 0.2s ease;
+}
+
+.stage.active {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.stage-top {
   display: flex;
+  gap: 0.5rem;
   align-items: center;
-  gap: 0.75rem;
+  margin-bottom: 0.25rem;
 }
 
-.era-item:hover {
-  border-color: var(--vp-c-brand);
-  transform: translateY(-2px);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
-}
-
-.era-item.active {
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-}
-
-.era-marker {
-  width: 32px;
-  height: 32px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  font-size: 0.9rem;
-  flex-shrink: 0;
-}
-
-.era-content {
-  flex: 1;
-  min-width: 0;
-}
-
-.era-title {
-  font-weight: 600;
-  font-size: 0.9rem;
-  margin-bottom: 0.2rem;
-}
-
-.era-year {
-  font-size: 0.8rem;
-  color: var(--vp-c-text-2);
-}
-
-.era-details {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.era-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  margin-bottom: 1rem;
-  gap: 1rem;
-}
-
-.era-header h3 {
-  margin: 0;
+.icon {
   font-size: 1.1rem;
-  font-weight: 700;
 }
 
-.era-badge {
-  background: var(--vp-c-brand);
-  color: white;
-  padding: 0.25rem 0.75rem;
-  border-radius: 6px;
-  font-size: 0.85rem;
-  font-weight: 600;
+.name {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
-.era-description {
+.stage-sub {
   color: var(--vp-c-text-2);
-  line-height: 1.6;
-  margin-bottom: 1.25rem;
-}
-
-.era-flow {
-  margin-bottom: 1.25rem;
-}
-
-.flow-title {
-  font-weight: 600;
-  margin-bottom: 0.75rem;
-  font-size: 0.95rem;
-}
-
-.flow-steps {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.5rem;
-  align-items: center;
-}
-
-.flow-step {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-.step-number {
-  width: 24px;
-  height: 24px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 0.75rem;
-  font-weight: 600;
-  flex-shrink: 0;
-}
-
-.step-content {
-  background: var(--vp-c-bg-soft);
-  padding: 0.4rem 0.75rem;
-  border-radius: 6px;
   font-size: 0.85rem;
+  line-height: 1.4;
+}
+
+.card {
+  background: var(--vp-c-bg);
   border: 1px solid var(--vp-c-divider);
-}
-
-.step-arrow {
-  color: var(--vp-c-text-2);
-  font-weight: 600;
-}
-
-.era-pros-cons {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-  gap: 1rem;
-  margin-bottom: 1.25rem;
-}
-
-.pros,
-.cons {
-  background: var(--vp-c-bg-soft);
   border-radius: 8px;
   padding: 1rem;
-  border: 1px solid var(--vp-c-divider);
 }
 
-.list-title {
-  font-weight: 600;
+.card-title {
+  font-weight: 800;
   margin-bottom: 0.5rem;
-  font-size: 0.9rem;
+  color: var(--vp-c-text-1);
 }
 
-.pros ul {
-  margin: 0;
-  padding-left: 1.25rem;
-}
-
-.pros li {
-  margin-bottom: 0.4rem;
-  font-size: 0.85rem;
-  color: #16a34a;
-}
-
-.cons ul {
-  margin: 0;
-  padding-left: 1.25rem;
-}
-
-.cons li {
-  margin-bottom: 0.4rem;
-  font-size: 0.85rem;
-  color: #ef4444;
-}
-
-.era-usecase {
-  background: rgba(59, 130, 246, 0.1);
-  border-left: 3px solid var(--vp-c-brand);
-  padding: 0.75rem 1rem;
-  border-radius: 6px;
-}
-
-.usecase-title {
-  font-weight: 600;
-  margin-bottom: 0.4rem;
-  font-size: 0.9rem;
-  color: var(--vp-c-brand);
-}
-
-.usecase-content {
-  font-size: 0.85rem;
+.desc {
   color: var(--vp-c-text-2);
-  line-height: 1.5;
+  line-height: 1.75;
+  margin-bottom: 0.75rem;
 }
 
-@media (max-width: 768px) {
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.box {
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+
+.box-title {
+  font-weight: 800;
+  margin-bottom: 0.5rem;
+  color: var(--vp-c-text-1);
+}
+
+.list {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+.code {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+}
+
+@media (max-width: 720px) {
   .timeline {
-    flex-direction: column;
+    grid-template-columns: 1fr;
   }
-
-  .era-item {
-    min-width: auto;
-  }
-
-  .era-pros-cons {
+  .grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/AuthInteractiveLoginDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/AuthInteractiveLoginDemo.vue
new file mode 100644
index 0000000..86569b1
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/auth-design/AuthInteractiveLoginDemo.vue
@@ -0,0 +1,862 @@
+<!--
+  AuthInteractiveLoginDemo.vue
+  交互式登录流程演示
+
+  用途：
+  通过模拟真实的登录流程，让用户直观理解认证和授权的概念。
+
+  互动功能：
+  - 模拟登录：输入用户名密码，看到完整的认证流程
+  - 可视化数据流：HTTP 请求和响应的实时展示
+  - 两种模式对比：Session vs JWT
+-->
+<template>
+  <div class="auth-interactive-login">
+    <div class="header">
+      <div class="title">🔐 认证流程演示</div>
+      <div class="subtitle">模拟登录过程，理解认证与授权的区别</div>
+    </div>
+
+    <!-- 模式切换 -->
+    <div class="mode-selector">
+      <div class="mode-label">选择鉴权方式：</div>
+      <div class="mode-buttons">
+        <button
+          class="mode-btn"
+          :class="{ active: mode === 'session' }"
+          @click="switchMode('session')"
+        >
+          🍪 Session + Cookie
+        </button>
+        <button
+          class="mode-btn"
+          :class="{ active: mode === 'jwt' }"
+          @click="switchMode('jwt')"
+        >
+          🎫 JWT Token
+        </button>
+      </div>
+    </div>
+
+    <div class="main-content">
+      <!-- 登录表单 -->
+      <div class="login-section">
+        <div class="form-container">
+          <div class="form-title">登录表单</div>
+          <div class="form-fields">
+            <div class="field-group">
+              <label>用户名</label>
+              <input
+                type="text"
+                v-model="username"
+                placeholder="输入用户名"
+                :disabled="locked"
+              />
+            </div>
+            <div class="field-group">
+              <label>密码</label>
+              <input
+                type="password"
+                v-model="password"
+                placeholder="输入密码"
+                :disabled="locked"
+                @keyup.enter="startDemo"
+              />
+            </div>
+            <button
+              class="login-btn"
+              @click="startDemo"
+              :disabled="!username || !password || locked"
+            >
+              开始演示
+            </button>
+          </div>
+
+          <div class="hints">
+            <div class="hint-title">💡 提示</div>
+            <div class="hint-text">
+              试试用户名 <code>admin</code>，密码 <code>123456</code>
+            </div>
+          </div>
+
+          <div class="stepper" v-if="flowStep > 0">
+            <div class="stepper-title">
+              当前步骤：{{ flowStep }} / {{ maxStep }}
+              <span class="stepper-hint"
+                >（手动推进，避免“自动下一步”误解）</span
+              >
+            </div>
+            <div class="stepper-actions">
+              <button
+                class="step-btn"
+                @click="prevStep"
+                :disabled="flowStep <= 1"
+              >
+                上一步
+              </button>
+              <button
+                class="step-btn primary"
+                @click="nextStep"
+                :disabled="flowStep >= maxStep"
+              >
+                下一步
+              </button>
+              <button class="step-btn" @click="resetDemo">重置</button>
+            </div>
+          </div>
+        </div>
+
+        <!-- 实时数据流 -->
+        <div class="data-flow">
+          <div class="flow-title">📊 数据流可视化</div>
+
+          <!-- 请求阶段 -->
+          <div class="flow-stage request-stage" v-if="currentStage >= 1">
+            <div class="stage-header">
+              <span class="stage-badge">{{
+                currentStage === 1 ? '📤' : '✅'
+              }}</span>
+              <span class="stage-name">1. 客户端发送登录请求</span>
+            </div>
+            <div class="request-content" v-if="currentStage >= 1">
+              <div class="request-line">
+                <span class="method">POST</span>
+                <span class="path">/api/login</span>
+              </div>
+              <div class="request-body">
+                <div class="body-title">Body:</div>
+                <pre>
+{
+  "username": "{{ username }}",
+  "password": "******"
+}</pre
+                >
+              </div>
+            </div>
+          </div>
+
+          <div class="flow-arrow" v-if="currentStage >= 1">⬇️</div>
+
+          <!-- 服务器验证阶段 -->
+          <div class="flow-stage server-stage" v-if="currentStage >= 2">
+            <div class="stage-header">
+              <span class="stage-badge">{{
+                currentStage === 2 ? '⚙️' : '✅'
+              }}</span>
+              <span class="stage-name">2. 服务器验证身份</span>
+            </div>
+            <div class="server-content" v-if="currentStage >= 2">
+              <div class="verification-steps">
+                <div
+                  class="verify-step"
+                  :class="{ success: verificationStep >= 1 }"
+                >
+                  <span class="step-icon">{{
+                    verificationStep >= 1 ? '✅' : '⏳'
+                  }}</span>
+                  <span class="step-text">查询用户数据库</span>
+                </div>
+                <div
+                  class="verify-step"
+                  :class="{ success: verificationStep >= 2 }"
+                >
+                  <span class="step-icon">{{
+                    verificationStep >= 2 ? '✅' : '⏳'
+                  }}</span>
+                  <span class="step-text">验证密码哈希</span>
+                </div>
+                <div
+                  class="verify-step"
+                  :class="{ success: verificationStep >= 3 }"
+                >
+                  <span class="step-icon">{{
+                    verificationStep >= 3 ? '✅' : '⏳'
+                  }}</span>
+                  <span class="step-text"
+                    >生成{{
+                      mode === 'session' ? 'Session' : 'JWT Token'
+                    }}</span
+                  >
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <div class="flow-arrow" v-if="currentStage >= 2">⬇️</div>
+
+          <!-- 响应阶段 -->
+          <div class="flow-stage response-stage" v-if="currentStage >= 3">
+            <div class="stage-header">
+              <span class="stage-badge">{{
+                currentStage === 3 ? '📥' : '✅'
+              }}</span>
+              <span class="stage-name">3. 服务器返回认证结果</span>
+            </div>
+            <div class="response-content" v-if="authResult">
+              <div class="response-status success">✅ 登录成功</div>
+              <div class="response-body">
+                <div class="body-title">Response:</div>
+                <pre v-if="mode === 'session'">
+{
+  "status": "success",
+  "user": {
+    "id": 123,
+    "username": "{{ username }}"
+  }
+}</pre
+                >
+                <pre v-else>
+{
+  "status": "success",
+  "token": "{{ authResult?.token }}",
+  "user": {
+    "id": 123,
+    "username": "{{ username }}"
+  }
+}</pre
+                >
+              </div>
+              <div class="auth-mechanism" v-if="currentStage >= 4">
+                <div class="mechanism-title">
+                  {{ mode === 'session' ? '🍪 Cookie 设置' : '🎫 Token 存储' }}
+                </div>
+                <div class="mechanism-content">
+                  <div v-if="mode === 'session'">
+                    <code
+                      >Set-Cookie: session_id={{ authResult?.sessionId }};
+                      HttpOnly; Secure</code
+                    >
+                  </div>
+                  <div v-else>
+                    <code
+                      >localStorage.setItem("token", "{{
+                        authResult?.token
+                      }}")</code
+                    >
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <!-- 后续请求 -->
+          <div class="flow-stage request-stage" v-if="currentStage >= 5">
+            <div class="stage-header">
+              <span class="stage-badge">🔄</span>
+              <span class="stage-name">4. 后续请求自动携带认证信息</span>
+            </div>
+            <div class="subsequent-request">
+              <div class="request-line">
+                <span class="method">GET</span>
+                <span class="path">/api/user/profile</span>
+              </div>
+              <div class="auth-header">
+                <div class="header-title">Header:</div>
+                <div v-if="mode === 'session'">
+                  <code>Cookie: session_id={{ authResult?.sessionId }}</code>
+                </div>
+                <div v-else>
+                  <code>Authorization: Bearer {{ authResult?.token }}</code>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- 状态说明 -->
+    <div class="state-description" v-if="currentStage >= 4">
+      <div class="description-title">
+        📖 {{ mode === 'session' ? 'Session' : 'JWT' }} 工作原理
+      </div>
+      <div class="description-content">
+        <p v-if="mode === 'session'">
+          <strong>Session 模式：</strong>服务器在内存或 Redis 中创建一个
+          Session，存储用户信息。 服务器返回一个
+          <code>session_id</code> 给客户端，客户端后续请求会自动在 Cookie
+          中携带这个 ID。 服务器根据 ID 查找对应的 Session，从而识别用户身份。
+        </p>
+        <p v-else>
+          <strong>JWT 模式：</strong>服务器将用户信息编码成 JWT
+          Token，直接返回给客户端。 客户端将 Token 存储在
+          localStorage，后续请求在 <code>Authorization</code> Header 中携带。
+          服务器验证 Token 的签名即可识别用户，无需存储状态。
+        </p>
+      </div>
+    </div>
+
+    <!-- 重置按钮 -->
+    <div class="reset-section" v-if="currentStage >= 5">
+      <button class="reset-btn" @click="resetDemo">🔄 重新演示</button>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, ref } from 'vue'
+
+const mode = ref('session') // 'session' or 'jwt'
+const username = ref('')
+const password = ref('')
+const flowStep = ref(0) // 0 = not started, 1..maxStep = manual steps
+const authResult = ref(null)
+const locked = ref(false)
+
+const maxStep = 7
+
+const currentStage = computed(() => {
+  if (flowStep.value === 0) return 0
+  if (flowStep.value === 1) return 1
+  if (flowStep.value >= 2 && flowStep.value <= 4) return 2
+  if (flowStep.value === 5) return 3
+  if (flowStep.value === 6) return 4
+  return 5
+})
+
+const verificationStep = computed(() => {
+  if (flowStep.value < 2) return 0
+  if (flowStep.value === 2) return 1
+  if (flowStep.value === 3) return 2
+  return 3
+})
+
+const switchMode = (newMode) => {
+  mode.value = newMode
+  resetDemo()
+}
+
+const buildAuthResult = () => {
+  if (mode.value === 'session') {
+    return {
+      sessionId: 'sess_' + Math.random().toString(36).substring(2, 15)
+    }
+  }
+
+  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
+  const payload = btoa(
+    JSON.stringify({
+      user_id: 123,
+      username: username.value,
+      exp: Math.floor(Date.now() / 1000) + 3600
+    })
+  )
+  const signature = btoa(`${header}.${payload}.secret`)
+  return {
+    token: `${header}.${payload}.${signature}`.substring(0, 50) + '...'
+  }
+}
+
+const startDemo = () => {
+  if (!username.value || !password.value) return
+
+  // Start at step 1 (request). Other steps are manual via Next.
+  authResult.value = buildAuthResult()
+  flowStep.value = 1
+  locked.value = true
+}
+
+const nextStep = () => {
+  flowStep.value = Math.min(maxStep, flowStep.value + 1)
+}
+
+const prevStep = () => {
+  flowStep.value = Math.max(1, flowStep.value - 1)
+}
+
+const resetDemo = () => {
+  username.value = ''
+  password.value = ''
+  flowStep.value = 0
+  authResult.value = null
+  locked.value = false
+}
+</script>
+
+<style scoped>
+.auth-interactive-login {
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  border-radius: 8px;
+  padding: 1.5rem;
+  margin: 1rem 0;
+}
+
+.header {
+  margin-bottom: 1.5rem;
+  text-align: center;
+}
+
+.title {
+  font-weight: 700;
+  font-size: 1.2rem;
+  margin-bottom: 0.3rem;
+  color: var(--vp-c-text-1);
+}
+
+.subtitle {
+  color: var(--vp-c-text-2);
+  font-size: 0.9rem;
+}
+
+/* 模式切换 */
+.mode-selector {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+  flex-wrap: wrap;
+}
+
+.mode-label {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.mode-buttons {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.mode-btn {
+  padding: 0.6rem 1.2rem;
+  border: 2px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+  cursor: pointer;
+  font-size: 0.9rem;
+  font-weight: 600;
+  transition: all 0.2s ease;
+}
+
+.mode-btn:hover {
+  border-color: var(--vp-c-brand);
+  transform: translateY(-1px);
+}
+
+.mode-btn.active {
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+  border-color: var(--vp-c-brand);
+}
+
+/* 主内容 */
+.main-content {
+  display: grid;
+  grid-template-columns: 1fr 1.5fr;
+  gap: 1.5rem;
+  margin-bottom: 1.5rem;
+}
+
+/* 登录表单 */
+.login-section {
+  display: contents;
+}
+
+.form-container {
+  background: var(--vp-c-bg);
+  border-radius: 10px;
+  padding: 1.5rem;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.stepper {
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.stepper-title {
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  font-size: 0.9rem;
+  margin-bottom: 0.5rem;
+}
+
+.stepper-hint {
+  margin-left: 0.5rem;
+  font-weight: 500;
+  color: var(--vp-c-text-2);
+}
+
+.stepper-actions {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.step-btn {
+  padding: 0.5rem 0.8rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 600;
+  font-size: 0.875rem;
+}
+
+.step-btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.step-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.form-title {
+  font-weight: 700;
+  font-size: 1rem;
+  margin-bottom: 1rem;
+}
+
+.form-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.field-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+
+.field-group label {
+  font-weight: 600;
+  font-size: 0.85rem;
+  color: var(--vp-c-text-2);
+}
+
+.field-group input {
+  padding: 0.6rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  font-size: 0.9rem;
+  transition: border-color 0.2s;
+}
+
+.field-group input:focus {
+  outline: none;
+  border-color: var(--vp-c-brand);
+}
+
+.field-group input:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.login-btn {
+  padding: 0.75rem;
+  border: none;
+  border-radius: 6px;
+  background: var(--vp-c-brand);
+  color: white;
+  font-weight: 600;
+  font-size: 0.95rem;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.login-btn:hover:not(:disabled) {
+  background: #2563eb;
+  transform: translateY(-1px);
+}
+
+.login-btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.hints {
+  margin-top: 1rem;
+  padding: 0.75rem;
+  background: rgba(59, 130, 246, 0.1);
+  border-left: 3px solid var(--vp-c-brand);
+  border-radius: 6px;
+}
+
+.hint-title {
+  font-weight: 600;
+  font-size: 0.85rem;
+  margin-bottom: 0.3rem;
+  color: var(--vp-c-brand);
+}
+
+.hint-text {
+  font-size: 0.8rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.5;
+}
+
+.hint-text code {
+  background: var(--vp-c-bg);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.8rem;
+}
+
+/* 数据流 */
+.data-flow {
+  background: var(--vp-c-bg);
+  border-radius: 10px;
+  padding: 1.5rem;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.flow-title {
+  font-weight: 700;
+  font-size: 1rem;
+  margin-bottom: 1rem;
+}
+
+.flow-stage {
+  background: var(--vp-c-bg-soft);
+  border-radius: 8px;
+  padding: 1rem;
+  border: 1px solid var(--vp-c-divider);
+  animation: slideIn 0.4s ease;
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.stage-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.75rem;
+}
+
+.stage-badge {
+  font-size: 1.2rem;
+}
+
+.stage-name {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.request-line {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.method {
+  font-weight: 700;
+  color: #16a34a;
+  font-family: 'Courier New', monospace;
+}
+
+.path {
+  font-family: 'Courier New', monospace;
+  color: var(--vp-c-text-1);
+}
+
+.request-body,
+.response-body {
+  background: #1e293b;
+  border-radius: 6px;
+  padding: 0.75rem;
+  margin-top: 0.5rem;
+}
+
+.body-title,
+.header-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: #94a3b8;
+  margin-bottom: 0.4rem;
+}
+
+.request-body pre,
+.response-body pre {
+  margin: 0;
+  font-family: 'Courier New', monospace;
+  font-size: 0.75rem;
+  color: #e2e8f0;
+  line-height: 1.5;
+}
+
+/* 验证步骤 */
+.verification-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.verify-step {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem;
+  background: white;
+  border-radius: 6px;
+  font-size: 0.85rem;
+  transition: all 0.3s ease;
+}
+
+.verify-step.success {
+  background: rgba(34, 197, 94, 0.1);
+}
+
+.step-icon {
+  font-size: 1rem;
+}
+
+.step-text {
+  flex: 1;
+}
+
+/* 响应 */
+.response-status {
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  font-weight: 600;
+  font-size: 0.9rem;
+  margin-bottom: 0.75rem;
+}
+
+.response-status.success {
+  background: rgba(34, 197, 94, 0.1);
+  color: #16a34a;
+}
+
+/* 认证机制 */
+.auth-mechanism {
+  margin-top: 1rem;
+  padding: 0.75rem;
+  background: rgba(59, 130, 246, 0.1);
+  border-left: 3px solid var(--vp-c-brand);
+  border-radius: 6px;
+}
+
+.mechanism-title {
+  font-weight: 600;
+  font-size: 0.85rem;
+  margin-bottom: 0.5rem;
+  color: var(--vp-c-brand);
+}
+
+.mechanism-content code {
+  display: block;
+  background: #1e293b;
+  color: #e2e8f0;
+  padding: 0.5rem;
+  border-radius: 4px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.75rem;
+  word-break: break-all;
+}
+
+/* 后续请求 */
+.subsequent-request {
+  margin-top: 0.5rem;
+}
+
+.auth-header {
+  margin-top: 0.5rem;
+}
+
+.auth-header code {
+  display: block;
+  background: #1e293b;
+  color: #e2e8f0;
+  padding: 0.5rem;
+  border-radius: 4px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.75rem;
+  word-break: break-all;
+}
+
+.flow-arrow {
+  text-align: center;
+  font-size: 1.5rem;
+  color: var(--vp-c-text-2);
+  margin: 0.5rem 0;
+}
+
+/* 状态说明 */
+.state-description {
+  background: var(--vp-c-bg);
+  border-radius: 10px;
+  padding: 1.5rem;
+  border: 1px solid var(--vp-c-divider);
+  margin-bottom: 1.5rem;
+}
+
+.description-title {
+  font-weight: 700;
+  font-size: 1rem;
+  margin-bottom: 0.75rem;
+}
+
+.description-content {
+  font-size: 0.9rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+.description-content code {
+  background: var(--vp-c-bg-soft);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.85rem;
+  color: var(--vp-c-brand);
+}
+
+/* 重置 */
+.reset-section {
+  text-align: center;
+}
+
+.reset-btn {
+  padding: 0.75rem 2rem;
+  border: none;
+  border-radius: 8px;
+  background: #64748b;
+  color: white;
+  font-weight: 600;
+  font-size: 0.95rem;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.reset-btn:hover {
+  background: #475569;
+  transform: translateY(-1px);
+}
+
+@media (max-width: 768px) {
+  .main-content {
+    grid-template-columns: 1fr;
+  }
+
+  .mode-selector {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .mode-buttons {
+    width: 100%;
+  }
+
+  .mode-btn {
+    flex: 1;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/AuthNvsAuthZDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/AuthNvsAuthZDemo.vue
index 23454a7..0c58dce 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/AuthNvsAuthZDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/AuthNvsAuthZDemo.vue
@@ -1,654 +1,288 @@
 <!--
   AuthNvsAuthZDemo.vue
-  认证 vs 授权对比演示
+  AuthN vs AuthZ（更可用：请求模拟器）
 -->
 <template>
-  <div class="auth-n-vs-z-demo">
+  <div class="authn-authz-demo">
     <div class="header">
-      <div class="title">认证 vs 授权</div>
-      <div class="subtitle">先认证，再授权 - 两个不同的概念</div>
-    </div>
-
-    <div class="comparison">
-      <div class="comparison-card authn">
-        <div class="card-header">
-          <div class="card-icon">🔐</div>
-          <div class="card-title">Authentication (认证)</div>
-          <div class="card-abbr">AuthN</div>
-        </div>
-        <div class="card-content">
-          <div class="question">你是谁？</div>
-          <div class="answer">验证用户身份</div>
-          <div class="examples">
-            <div class="example-title">常见方式：</div>
-            <div class="example-list">
-              <div class="example-item">🔑 输入用户名密码</div>
-              <div class="example-item">👆 指纹识别</div>
-              <div class="example-item">👤 人脸识别</div>
-              <div class="example-item">📱 短信验证码</div>
-            </div>
-          </div>
-          <div class="output">
-            <div class="output-title">输出：</div>
-            <div class="output-value">Token / Session</div>
-          </div>
-        </div>
-      </div>
-
-      <div class="vs-divider">VS</div>
-
-      <div class="comparison-card authz">
-        <div class="card-header">
-          <div class="card-icon">🛡️</div>
-          <div class="card-title">Authorization (授权)</div>
-          <div class="card-abbr">AuthZ</div>
-        </div>
-        <div class="card-content">
-          <div class="question">你能干什么？</div>
-          <div class="answer">检查用户权限</div>
-          <div class="examples">
-            <div class="example-title">权限类型：</div>
-            <div class="example-list">
-              <div class="example-item">👀 查看权限</div>
-              <div class="example-item">✏️ 编辑权限</div>
-              <div class="example-item">🗑️ 删除权限</div>
-              <div class="example-item">👨‍💼 管理员权限</div>
-            </div>
-          </div>
-          <div class="output">
-            <div class="output-title">输出：</div>
-            <div class="output-value">允许 / 拒绝</div>
-          </div>
-        </div>
+      <div class="title">🪪 AuthN vs 🛂 AuthZ：一个请求到底会经历什么？</div>
+      <div class="subtitle">
+        选择“谁在请求”与“要做什么”，看看认证/授权分别在哪一步起作用。
       </div>
     </div>
 
-    <div class="flow-demo">
-      <div class="section-title">完整流程</div>
-      <div class="flow-steps">
-        <div
-          v-for="(step, index) in flowSteps"
-          :key="index"
-          class="flow-step"
-          :class="{
-            active: currentStep === index,
-            completed: currentStep > index
-          }"
-        >
-          <div class="step-circle">
-            {{ index + 1 }}
-          </div>
-          <div class="step-content">
-            <div class="step-title">{{ step.title }}</div>
-            <div class="step-desc">{{ step.desc }}</div>
-          </div>
-          <div v-if="index < flowSteps.length - 1" class="step-arrow">→</div>
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">选择请求</div>
+
+        <label class="label">身份（AuthN：你是谁）</label>
+        <div class="row">
+          <button
+            v-for="u in users"
+            :key="u.id"
+            class="chip"
+            :class="{ active: userId === u.id }"
+            @click="userId = u.id"
+          >
+            {{ u.name }}
+          </button>
+        </div>
+
+        <label class="label">操作（AuthZ：你能做什么）</label>
+        <div class="row">
+          <button
+            v-for="a in actions"
+            :key="a.id"
+            class="chip"
+            :class="{ active: actionId === a.id }"
+            @click="actionId = a.id"
+          >
+            {{ a.name }}
+          </button>
+        </div>
+
+        <div class="hint">
+          真实系统里：认证先发生（解析
+          cookie/JWT），授权发生在路由/业务逻辑层（RBAC/ABAC）。
         </div>
       </div>
 
-      <div class="scenario-demo">
-        <div class="scenario-header">模拟场景</div>
-        <div class="scenario-content">
-          <div class="user-action">
-            <div class="action-label">用户操作：</div>
-            <select v-model="selectedAction" @change="runScenario">
-              <option value="view">查看文章</option>
-              <option value="edit">编辑文章</option>
-              <option value="delete">删除文章</option>
-              <option value="admin">访问管理后台</option>
-            </select>
-          </div>
+      <div class="card">
+        <div class="card-title">模拟结果</div>
 
-          <div class="user-role">
-            <div class="role-label">用户角色：</div>
-            <div class="role-buttons">
-              <button
-                v-for="role in roles"
-                :key="role.key"
-                class="role-btn"
-                :class="{ active: selectedRole === role.key }"
-                @click="setRole(role.key)"
-              >
-                {{ role.label }}
-              </button>
-            </div>
+        <div class="result">
+          <div class="line">
+            <span class="k">AuthN（认证）</span>
+            <span class="v" :class="authn.ok ? 'ok' : 'bad'">
+              {{ authn.ok ? '通过' : '失败' }}
+            </span>
           </div>
-
-          <div class="result-box" :class="resultClass">
-            <div class="result-icon">{{ resultIcon }}</div>
-            <div class="result-text">{{ resultText }}</div>
+          <div class="line">
+            <span class="k">AuthZ（授权）</span>
+            <span class="v" :class="authz.ok ? 'ok' : 'bad'">
+              {{ authz.ok ? '允许' : '拒绝' }}
+            </span>
           </div>
-
-          <div class="step-details" v-if="stepDetails.length > 0">
-            <div class="step-details-title">处理流程：</div>
-            <div
-              class="step-detail-item"
-              v-for="(detail, idx) in stepDetails"
-              :key="idx"
-            >
-              <span class="detail-step">步骤 {{ idx + 1 }}：</span>
-              <span class="detail-text">{{ detail }}</span>
-            </div>
+          <div class="line">
+            <span class="k">HTTP</span>
+            <span class="v mono">{{ finalStatus }}</span>
           </div>
         </div>
+
+        <pre class="code"><code>{{ decisionLog }}</code></pre>
       </div>
     </div>
 
-    <div class="key-insight">
-      <div class="insight-icon">💡</div>
-      <div class="insight-text">
-        <strong>核心关系：</strong>先认证（AuthN），再授权（AuthZ）。
-        只有确认了"你是谁"，才能判断"你能干什么"。
-      </div>
+    <div class="card">
+      <div class="card-title">关键点</div>
+      <ul class="list">
+        <li><strong>认证失败：</strong>你是谁都不确定 → 通常返回 401。</li>
+        <li>
+          <strong>认证通过但没权限：</strong>你是谁确定了，但不能做 → 通常返回
+          403。
+        </li>
+        <li>
+          <strong>授权规则要在服务端：</strong
+          >别相信前端的“是否显示按钮”，那只是 UX。
+        </li>
+      </ul>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const currentStep = ref(0)
-const selectedAction = ref('view')
-const selectedRole = ref('user')
-
-const roles = [
-  { key: 'guest', label: '访客' },
-  { key: 'user', label: '普通用户' },
-  { key: 'admin', label: '管理员' }
+const users = [
+  { id: 'anon', name: '匿名用户' },
+  { id: 'user', name: '普通用户' },
+  { id: 'admin', name: '管理员' }
 ]
 
-const flowSteps = [
-  {
-    title: '用户请求',
-    desc: '用户发起操作请求'
-  },
-  {
-    title: '认证 (AuthN)',
-    desc: '验证 Token 是否有效'
-  },
-  {
-    title: '授权 (AuthZ)',
-    desc: '检查是否有权限'
-  },
-  {
-    title: '执行业务逻辑',
-    desc: '允许或拒绝访问'
-  }
+const actions = [
+  { id: 'view_profile', name: '查看个人资料（/api/me）' },
+  { id: 'create_post', name: '发帖（POST /posts）' },
+  { id: 'delete_user', name: '删除用户（DELETE /users/:id）' }
 ]
 
-const actionPermissions = {
-  view: { guest: true, user: true, admin: true },
-  edit: { guest: false, user: true, admin: true },
-  delete: { guest: false, user: false, admin: true },
-  admin: { guest: false, user: false, admin: true }
-}
+const userId = ref('anon')
+const actionId = ref('view_profile')
 
-const actionNames = {
-  view: '查看文章',
-  edit: '编辑文章',
-  delete: '删除文章',
-  admin: '访问管理后台'
-}
+const authn = computed(() => {
+  if (userId.value === 'anon')
+    return { ok: false, reason: '缺少有效凭证（cookie/JWT）' }
+  return { ok: true, reason: `识别为 ${userId.value}` }
+})
 
-const stepDetails = ref([])
-
-const resultText = computed(() => {
-  const hasPermission =
-    actionPermissions[selectedAction.value][selectedRole.value]
-  const action = actionNames[selectedAction.value]
-  const role = roles.find((r) => r.key === selectedRole.value)?.label
-
-  if (!hasPermission) {
-    return `${role}无法${action} - 权限不足`
+const authz = computed(() => {
+  if (!authn.value.ok)
+    return { ok: false, reason: '认证未通过，无法做授权判断' }
+  if (actionId.value === 'delete_user') {
+    return userId.value === 'admin'
+      ? { ok: true, reason: 'admin 允许删除用户' }
+      : { ok: false, reason: '只有 admin 才能删除用户' }
   }
-  return `${role}可以${action} - 授权通过`
+  return { ok: true, reason: '此操作对已登录用户开放' }
 })
 
-const resultClass = computed(() => {
-  const hasPermission =
-    actionPermissions[selectedAction.value][selectedRole.value]
-  return hasPermission ? 'success' : 'error'
+const finalStatus = computed(() => {
+  if (!authn.value.ok) return '401 Unauthorized'
+  if (!authz.value.ok) return '403 Forbidden'
+  return '200 OK'
 })
 
-const resultIcon = computed(() => {
-  const hasPermission =
-    actionPermissions[selectedAction.value][selectedRole.value]
-  return hasPermission ? '✅' : '❌'
+const decisionLog = computed(() => {
+  const lines = []
+  lines.push(`Request: ${actionId.value}`)
+  lines.push(
+    `AuthN: ${authn.value.ok ? 'PASS' : 'FAIL'} - ${authn.value.reason}`
+  )
+  lines.push(
+    `AuthZ: ${authz.value.ok ? 'ALLOW' : 'DENY'} - ${authz.value.reason}`
+  )
+  lines.push(`Result: ${finalStatus.value}`)
+  return lines.join('\n')
 })
-
-const setRole = (role) => {
-  selectedRole.value = role
-  runScenario()
-}
-
-const runScenario = () => {
-  const action = selectedAction.value
-  const role = selectedRole.value
-  const hasPermission = actionPermissions[action][role]
-
-  stepDetails.value = [
-    `用户请求：${actionNames[action]}`,
-    `认证检查：${role !== 'guest' ? '已登录，Token 有效' : '未登录或 Token 无效'}`,
-    `授权检查：检查 ${role} 是否有 ${action} 权限`,
-    `最终决定：${hasPermission ? '允许访问' : '拒绝访问，返回 403 Forbidden'}`
-  ]
-
-  currentStep.value = 4
-}
 </script>
 
 <style scoped>
-.auth-n-vs-z-demo {
+.authn-authz-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
-.comparison {
-  display: flex;
-  align-items: stretch;
-  gap: 1.5rem;
-  margin-bottom: 2rem;
-  flex-wrap: wrap;
-}
-
-.comparison-card {
-  flex: 1;
-  min-width: 280px;
-  background: var(--vp-c-bg);
-  border-radius: 12px;
-  padding: 1.5rem;
-  border: 2px solid var(--vp-c-divider);
-  transition: all 0.2s ease;
-}
-
-.comparison-card:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 6px 16px rgba(0, 0, 0, 0.1);
-}
-
-.comparison-card.authn {
-  border-color: #3b82f6;
-}
-
-.comparison-card.authz {
-  border-color: #8b5cf6;
-}
-
-.card-header {
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
   margin-bottom: 1rem;
-  flex-wrap: wrap;
 }
 
-.card-icon {
-  font-size: 2rem;
+.card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
 }
 
 .card-title {
-  flex: 1;
-  font-weight: 700;
-  font-size: 1rem;
+  font-weight: 800;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
 }
 
-.card-abbr {
-  background: var(--vp-c-brand);
-  color: white;
-  padding: 0.25rem 0.6rem;
-  border-radius: 6px;
-  font-size: 0.75rem;
-  font-weight: 600;
+.label {
+  display: block;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  font-size: 0.875rem;
+  margin: 0.75rem 0 0.35rem;
 }
 
-.comparison-card.authn .card-abbr {
-  background: #3b82f6;
-}
-
-.comparison-card.authz .card-abbr {
-  background: #8b5cf6;
-}
-
-.question {
-  font-size: 1.2rem;
-  font-weight: 700;
-  margin-bottom: 0.5rem;
-}
-
-.answer {
-  color: var(--vp-c-text-2);
-  font-size: 0.9rem;
-  margin-bottom: 1rem;
-}
-
-.examples {
-  margin-bottom: 1rem;
-}
-
-.example-title {
-  font-weight: 600;
-  font-size: 0.85rem;
-  margin-bottom: 0.5rem;
-}
-
-.example-list {
-  display: flex;
-  flex-direction: column;
-  gap: 0.4rem;
-}
-
-.example-item {
-  font-size: 0.85rem;
-  padding: 0.4rem 0.6rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 6px;
-  border-left: 3px solid var(--vp-c-brand);
-}
-
-.comparison-card.authn .example-item {
-  border-color: #3b82f6;
-}
-
-.comparison-card.authz .example-item {
-  border-color: #8b5cf6;
-}
-
-.output {
-  padding: 0.75rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  border-left: 3px solid var(--vp-c-brand);
-}
-
-.comparison-card.authn .output {
-  border-color: #3b82f6;
-}
-
-.comparison-card.authz .output {
-  border-color: #8b5cf6;
-}
-
-.output-title {
-  font-size: 0.8rem;
-  font-weight: 600;
-  margin-bottom: 0.3rem;
-}
-
-.output-value {
-  font-size: 0.95rem;
-  font-weight: 700;
-}
-
-.vs-divider {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 700;
-  font-size: 1.2rem;
-  color: var(--vp-c-text-2);
-  min-width: 50px;
-}
-
-.flow-demo {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.section-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.flow-steps {
-  display: flex;
-  align-items: stretch;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-  overflow-x: auto;
-  padding-bottom: 0.5rem;
-}
-
-.flow-step {
-  flex: 1;
-  min-width: 140px;
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.75rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.flow-step.active {
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-}
-
-.flow-step.completed {
-  opacity: 0.6;
-}
-
-.step-circle {
-  width: 28px;
-  height: 28px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  font-size: 0.85rem;
-  flex-shrink: 0;
-}
-
-.step-content {
-  flex: 1;
-  min-width: 0;
-}
-
-.step-title {
-  font-weight: 600;
-  font-size: 0.85rem;
-  margin-bottom: 0.2rem;
-}
-
-.step-desc {
-  font-size: 0.75rem;
-  color: var(--vp-c-text-2);
-}
-
-.step-arrow {
-  color: var(--vp-c-text-2);
-  font-weight: 700;
-  flex-shrink: 0;
-}
-
-.scenario-demo {
-  margin-top: 1.5rem;
-  padding-top: 1.5rem;
-  border-top: 1px solid var(--vp-c-divider);
-}
-
-.scenario-header {
-  font-weight: 600;
-  margin-bottom: 1rem;
-  font-size: 0.95rem;
-}
-
-.scenario-content {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.user-action,
-.user-role {
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-}
-
-.action-label,
-.role-label {
-  font-weight: 600;
-  font-size: 0.9rem;
-  min-width: 80px;
-}
-
-.user-action select {
-  flex: 1;
-  min-width: 150px;
-  padding: 0.5rem;
-  border: 1px solid var(--vp-c-divider);
-  border-radius: 6px;
-  background: var(--vp-c-bg);
-  font-size: 0.9rem;
-}
-
-.role-buttons {
+.row {
   display: flex;
   gap: 0.5rem;
   flex-wrap: wrap;
 }
 
-.role-btn {
-  padding: 0.5rem 1rem;
+.chip {
+  padding: 0.4rem 0.65rem;
+  border-radius: 999px;
   border: 1px solid var(--vp-c-divider);
-  border-radius: 6px;
-  background: var(--vp-c-bg-soft);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
   cursor: pointer;
-  transition: all 0.2s ease;
-  font-size: 0.85rem;
+  font-weight: 700;
+  font-size: 0.875rem;
 }
 
-.role-btn:hover {
-  border-color: var(--vp-c-brand);
+.chip.active {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
 }
 
-.role-btn.active {
-  background: var(--vp-c-brand);
-  color: white;
-  border-color: var(--vp-c-brand);
+.hint {
+  margin-top: 0.75rem;
+  color: var(--vp-c-text-2);
+  font-size: 0.9rem;
+  line-height: 1.7;
 }
 
-.result-box {
-  padding: 1rem;
-  border-radius: 8px;
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  font-weight: 600;
-}
-
-.result-box.success {
-  background: rgba(34, 197, 94, 0.1);
-  border: 1px solid #22c55e;
-  color: #16a34a;
-}
-
-.result-box.error {
-  background: rgba(239, 68, 68, 0.1);
-  border: 1px solid #ef4444;
-  color: #dc2626;
-}
-
-.result-icon {
-  font-size: 1.5rem;
-}
-
-.step-details {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
+.result {
   border: 1px solid var(--vp-c-divider);
-}
-
-.step-details-title {
-  font-weight: 600;
-  font-size: 0.85rem;
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
   margin-bottom: 0.75rem;
 }
 
-.step-detail-item {
-  font-size: 0.85rem;
-  padding: 0.4rem 0;
-  border-bottom: 1px solid var(--vp-c-divider);
-}
-
-.step-detail-item:last-child {
-  border-bottom: none;
-}
-
-.detail-step {
-  font-weight: 600;
-  color: var(--vp-c-brand);
-}
-
-.key-insight {
+.line {
   display: flex;
+  justify-content: space-between;
   gap: 0.75rem;
-  background: rgba(59, 130, 246, 0.1);
-  border-left: 4px solid var(--vp-c-brand);
-  padding: 1rem;
-  border-radius: 8px;
+  padding: 0.35rem 0;
 }
 
-.insight-icon {
-  font-size: 1.5rem;
-  flex-shrink: 0;
+.k {
+  color: var(--vp-c-text-2);
+  font-weight: 700;
 }
 
-.insight-text {
-  font-size: 0.9rem;
-  line-height: 1.6;
+.v {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
-.insight-text strong {
-  color: var(--vp-c-brand);
+.v.ok {
+  color: var(--vp-c-green-1, #22c55e);
 }
 
-@media (max-width: 768px) {
-  .comparison {
-    flex-direction: column;
-  }
+.v.bad {
+  color: var(--vp-c-red-1, #ef4444);
+}
 
-  .vs-divider {
-    transform: rotate(90deg);
-    margin: 0.5rem 0;
-  }
+.mono {
+  font-family: var(--vp-font-family-mono);
+}
 
-  .flow-steps {
-    flex-direction: column;
-  }
+.code {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+}
 
-  .step-arrow {
-    transform: rotate(90deg);
+.list {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+@media (max-width: 720px) {
+  .grid {
+    grid-template-columns: 1fr;
   }
 }
 </style>
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/CSRFDefenseDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/CSRFDefenseDemo.vue
index 34427ba..40fcf0c 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/CSRFDefenseDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/CSRFDefenseDemo.vue
@@ -1,772 +1,294 @@
 <!--
   CSRFDefenseDemo.vue
-  CSRF 防御演示
+  CSRF 防护（手动推进 + “怎么做”清单）
 -->
 <template>
-  <div class="csrf-defense-demo">
+  <div class="csrf-demo">
     <div class="header">
-      <div class="title">CSRF 攻击与防御</div>
-      <div class="subtitle">Cross-Site Request Forgery 跨站请求伪造</div>
-    </div>
-
-    <div class="attack-demo">
-      <div class="demo-title">CSRF 攻击演示</div>
-      <div class="attack-scenario">
-        <div class="scenario-box good-site">
-          <div class="box-header">
-            <span class="box-icon">🏦</span>
-            <span class="box-title">银行网站 bank.com</span>
-          </div>
-          <div class="box-content">
-            <div class="login-status" :class="{ logged: isLoggedIn }">
-              {{ isLoggedIn ? '✅ 已登录' : '❌ 未登录' }}
-            </div>
-            <button
-              v-if="isLoggedIn"
-              class="action-btn transfer"
-              @click="performTransfer"
-            >
-              💰 转账
-            </button>
-            <button v-else class="action-btn login" @click="isLoggedIn = true">
-              🔑 登录银行
-            </button>
-            <div class="cookie-info" v-if="isLoggedIn">
-              <div class="info-title">浏览器 Cookie</div>
-              <div class="cookie-item">
-                <span class="cookie-key">session_id:</span>
-                <span class="cookie-value">bank_session_xyz</span>
-              </div>
-            </div>
-          </div>
-        </div>
-
-        <div class="scenario-arrow">→ 用户同时访问</div>
-
-        <div class="scenario-box evil-site">
-          <div class="box-header">
-            <span class="box-icon">😈</span>
-            <span class="box-title">恶意网站 evil.com</span>
-          </div>
-          <div class="box-content">
-            <div class="evil-content">
-              <p>🎣 欢迎来到抽奖活动！</p>
-              <button class="action-btn evil-btn" @click="triggerAttack">
-                🎁 点击抽奖
-              </button>
-              <div class="evil-code" v-if="attackTriggered">
-                <div class="code-title">恶意代码（隐藏）：</div>
-                <pre class="code-block">
-&lt;img src="https://bank.com/api/transfer?to=attacker&amount=10000" /&gt;</pre
-                >
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-
-      <div class="attack-result" v-if="attackResult">
-        <div class="result-box" :class="attackResult.type">
-          <div class="result-icon">{{ attackResult.icon }}</div>
-          <div class="result-text">{{ attackResult.text }}</div>
-        </div>
+      <div class="title">🛡️ CSRF：为什么“自动带 Cookie”会出事？</div>
+      <div class="subtitle">
+        手动推进一个最小攻击链，再看 3 个最常用防护手段（SameSite / CSRF Token /
+        双重提交）。
       </div>
     </div>
 
-    <div class="defense-mechanisms">
-      <div class="mechanisms-title">防御措施</div>
+    <div class="controls">
+      <button class="btn primary" @click="start" :disabled="step !== 0">
+        开始
+      </button>
+      <button class="btn" @click="prev" :disabled="step <= 1">上一步</button>
+      <button
+        class="btn primary"
+        @click="next"
+        :disabled="step === 0 || step >= maxStep"
+      >
+        下一步
+      </button>
+      <button class="btn" @click="reset">重置</button>
+    </div>
 
-      <div class="mechanism-tabs">
-        <button
-          v-for="mechanism in mechanisms"
-          :key="mechanism.key"
-          class="tab-btn"
-          :class="{ active: selectedMechanism === mechanism.key }"
-          @click="selectedMechanism = mechanism.key"
-        >
-          <span class="tab-icon">{{ mechanism.icon }}</span>
-          <span class="tab-label">{{ mechanism.name }}</span>
-        </button>
+    <div v-if="step > 0" class="progress">
+      Step {{ step }} / {{ maxStep }} · {{ steps[step - 1]?.title }}
+    </div>
+
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">场景</div>
+        <div class="desc">
+          假设你登录了 <strong>bank.com</strong>（Cookie
+          已存在）。你又打开了一个恶意网站
+          <strong>evil.com</strong>，它偷偷发起转账请求。
+        </div>
+        <div class="box">
+          <div class="box-title">你的 Cookie（浏览器会自动带）</div>
+          <code class="mono">Cookie: session_id=abc123</code>
+        </div>
       </div>
 
-      <div class="mechanism-content" v-if="currentMechanism">
-        <div class="mechanism-header">
-          <div class="header-title">{{ currentMechanism.title }}</div>
-          <div class="header-subtitle">{{ currentMechanism.subtitle }}</div>
-        </div>
-
-        <div class="mechanism-demo">
-          <div class="demo-flow">
-            <div class="flow-steps">
-              <div
-                v-for="(step, index) in currentMechanism.steps"
-                :key="index"
-                class="flow-step"
-              >
-                <div class="step-number">{{ index + 1 }}</div>
-                <div class="step-content">{{ step }}</div>
-              </div>
-            </div>
-          </div>
-
-          <div class="code-example" v-if="currentMechanism.code">
-            <div class="code-title">代码示例</div>
-            <pre class="code-block">{{ currentMechanism.code }}</pre>
-          </div>
-        </div>
-
-        <div class="mechanism-pros-cons">
-          <div class="pros">
-            <div class="list-title">优点</div>
-            <ul>
-              <li v-for="(pro, index) in currentMechanism.pros" :key="index">
-                {{ pro }}
-              </li>
-            </ul>
-          </div>
-          <div class="cons">
-            <div class="list-title">注意事项</div>
-            <ul>
-              <li v-for="(con, index) in currentMechanism.cons" :key="index">
-                {{ con }}
-              </li>
-            </ul>
-          </div>
-        </div>
+      <div class="card">
+        <div class="card-title">本步请求</div>
+        <pre class="code"><code>{{ requestText }}</code></pre>
+        <div class="desc">{{ steps[step - 1]?.desc }}</div>
       </div>
     </div>
 
-    <div class="comparison-table">
-      <div class="table-title">CSRF vs XSS 对比</div>
-      <table>
-        <thead>
-          <tr>
-            <th>特性</th>
-            <th>CSRF</th>
-            <th>XSS</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td><strong>攻击方式</strong></td>
-            <td>冒用用户身份发送请求</td>
-            <td>在网页注入恶意脚本</td>
-          </tr>
-          <tr>
-            <td><strong>攻击目标</strong></td>
-            <td>trusted 网站</td>
-            <td>网站的其他用户</td>
-          </tr>
-          <tr>
-            <td><strong>利用点</strong></td>
-            <td>浏览器自动带 Cookie</td>
-            <td>网站未过滤用户输入</td>
-          </tr>
-          <tr>
-            <td><strong>防御重点</strong></td>
-            <td>验证请求来源</td>
-            <td>输出转义、CSP</td>
-          </tr>
-        </tbody>
-      </table>
+    <div class="card">
+      <div class="card-title">防护怎么选？（优先顺序）</div>
+      <ol class="list">
+        <li>
+          <strong>SameSite Cookie：</strong
+          >对大多数“跨站表单/图片”请求非常有效（Lax/Strict）。
+        </li>
+        <li>
+          <strong>CSRF Token：</strong>在表单/请求头里带
+          token，服务端校验（对复杂场景最稳）。
+        </li>
+        <li>
+          <strong>双重提交 Cookie：</strong>Cookie + Header 同时带
+          token（服务端比较一致性）。
+        </li>
+      </ol>
+      <div class="warn">
+        <div class="warn-title">注意</div>
+        <div class="warn-text">
+          CSRF 主要针对“Cookie 自动携带”的场景。若你用 Authorization:
+          Bearer（不自动发送），CSRF 风险会显著降低，但仍要考虑 XSS/Token
+          泄露等问题。
+        </div>
+      </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const isLoggedIn = ref(false)
-const attackTriggered = ref(false)
-const attackResult = ref(null)
-const selectedMechanism = ref('csrf-token')
+const maxStep = 4
+const step = ref(0)
 
-const mechanisms = [
+const steps = [
   {
-    key: 'csrf-token',
-    icon: '🎫',
-    name: 'CSRF Token',
-    title: 'CSRF Token 验证',
-    subtitle: '在每个请求中添加随机 Token，服务端验证',
-    steps: [
-      '用户访问页面时，服务端生成随机 CSRF Token',
-      'Token 存储在 Session 中，并返回给前端',
-      '前端在表单中加入隐藏字段：&lt;input type="hidden" name="csrf_token" value="..."&gt;',
-      '提交表单时，服务端验证 Token 是否匹配',
-      'Token 只能用一次，验证后立即失效'
-    ],
-    code: `// 后端生成 Token
-app.get('/form', (req, res) => {
-  const token = generateRandomToken()
-  req.session.csrf_token = token
-  res.render('form', { csrf_token: token })
-})
-
-// 验证 Token
-app.post('/transfer', (req, res) => {
-  if (req.body.csrf_token !== req.session.csrf_token) {
-    return res.status(403).send('CSRF Token 无效')
-  }
-  // 执行转账
-})`,
-    pros: [
-      '✅ 最有效的 CSRF 防御方法',
-      '✅ Token 随机生成，攻击者无法预测',
-      '✅ 每次请求验证，安全性高'
-    ],
-    cons: ['⚠️ 需要在每个表单中添加 Token', '⚠️ 增加开发和维护成本']
+    title: '1) 恶意站点发起跨站请求',
+    desc: 'evil.com 诱导你点击按钮/加载图片/提交表单，目标是 bank.com 的转账接口。'
   },
   {
-    key: 'samesite',
-    icon: '🍪',
-    name: 'SameSite Cookie',
-    title: 'SameSite Cookie 属性',
-    subtitle: '限制 Cookie 在跨站请求时发送',
-    steps: [
-      '设置 Cookie 的 SameSite 属性',
-      'SameSite=Strict：只在同一站点请求时发送',
-      'SameSite=Lax：允许安全的跨站请求（如链接跳转）',
-      '浏览器自动阻止跨站请求携带 Cookie',
-      '无需修改应用代码'
-    ],
-    code: `// 设置 SameSite Cookie
-app.use(session({
-  secret: 'your-secret',
-  cookie: {
-    sameSite: 'strict', // 或 'lax'
-    secure: true,       // 只在 HTTPS 下传输
-    httpOnly: true      // 防止 JavaScript 读取
-  }
-}))`,
-    pros: [
-      '✅ 简单易用，只需设置 Cookie 属性',
-      '✅ 浏览器原生支持，无需修改应用逻辑',
-      '✅ 与其他防御方法兼容'
-    ],
-    cons: ['⚠️ 老版本浏览器不支持', '⚠️ 可能影响某些合法的跨站请求']
+    title: '2) 浏览器自动带上 bank.com 的 Cookie',
+    desc: '关键点：Cookie 是“按域名自动携带”的，evil.com 不需要知道你的 session_id。'
   },
   {
-    key: 'jwt',
-    icon: '🎫',
-    name: '使用 JWT',
-    title: 'JWT 替代 Cookie',
-    subtitle: '将 Token 存储在 localStorage，不使用 Cookie',
-    steps: [
-      '用户登录后，服务端生成 JWT',
-      '前端将 JWT 存储在 localStorage',
-      '每次请求在 Header 中携带：Authorization: Bearer &lt;token&gt;',
-      'localStorage 的内容不会自动发送',
-      '天然防 CSRF 攻击'
-    ],
-    code: `// 前端存储 JWT
-localStorage.setItem('token', jwt_token)
-
-// 发送请求时携带
-fetch('/api/data', {
-  headers: {
-    'Authorization': 'Bearer ' + localStorage.getItem('token')
-  }
-})`,
-    pros: [
-      '✅ 天然防 CSRF，Cookie 不自动携带',
-      '✅ 适合前后端分离和移动端',
-      '✅ 易于实现'
-    ],
-    cons: [
-      '⚠️ 容易受到 XSS 攻击',
-      '⚠️ 需要额外防范 XSS（HttpOnly Cookie 无法用）'
-    ]
+    title: '3) 服务端如果只靠 Cookie 识别用户，会误以为是你本人操作',
+    desc: '如果 bank.com 没做 CSRF 防护，转账可能被执行。'
+  },
+  {
+    title: '4) 加上 CSRF 防护后，请求会被拒绝',
+    desc: 'SameSite/CSRF Token 等会阻断这类跨站伪造请求。'
   }
 ]
 
-const currentMechanism = computed(() => {
-  return mechanisms.find((m) => m.key === selectedMechanism.value)
+const requestText = computed(() => {
+  if (step.value === 0) return '（点击开始）'
+  if (step.value === 1) {
+    return `POST https://bank.com/api/transfer
+Origin: https://evil.com
+Content-Type: application/x-www-form-urlencoded
+
+to=attacker&amount=1000`
+  }
+  if (step.value === 2) {
+    return `POST /api/transfer
+Origin: https://evil.com
+Cookie: session_id=abc123
+
+to=attacker&amount=1000`
+  }
+  if (step.value === 3) {
+    return `（如果服务端只校验 Cookie：可能返回 200 OK 并执行转账）`
+  }
+  return `POST /api/transfer
+Origin: https://evil.com
+Cookie: session_id=abc123
+X-CSRF-Token: <missing or invalid>
+
+→ 403 Forbidden`
 })
 
-const performTransfer = () => {
-  if (!isLoggedIn.value) return
-  alert('正常转账：转账成功')
+const start = () => {
+  step.value = 1
 }
 
-const triggerAttack = () => {
-  attackTriggered.value = true
+const next = () => {
+  step.value = Math.min(maxStep, step.value + 1)
+}
 
-  if (isLoggedIn.value) {
-    attackResult.value = {
-      type: 'danger',
-      icon: '⚠️',
-      text: 'CSRF 攻击成功！浏览器自动带上了银行的 Cookie，转账请求被发送。'
-    }
-  } else {
-    attackResult.value = {
-      type: 'warning',
-      icon: '🛡️',
-      text: '攻击失败：用户未登录银行网站。'
-    }
-  }
+const prev = () => {
+  step.value = Math.max(1, step.value - 1)
+}
+
+const reset = () => {
+  step.value = 0
 }
 </script>
 
 <style scoped>
-.csrf-defense-demo {
+.csrf-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
-.attack-demo {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.demo-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.attack-scenario {
-  display: grid;
-  grid-template-columns: 1fr auto 1fr;
-  gap: 1rem;
-  align-items: stretch;
-  margin-bottom: 1rem;
-}
-
-.scenario-box {
-  background: var(--vp-c-bg-soft);
-  border-radius: 10px;
-  padding: 1rem;
-  border: 2px solid var(--vp-c-divider);
+.controls {
   display: flex;
-  flex-direction: column;
-}
-
-.scenario-box.good-site {
-  border-color: #3b82f6;
-}
-
-.scenario-box.evil-site {
-  border-color: #ef4444;
-}
-
-.box-header {
-  display: flex;
-  align-items: center;
   gap: 0.5rem;
-  margin-bottom: 1rem;
-  padding-bottom: 0.75rem;
-  border-bottom: 1px solid var(--vp-c-divider);
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.box-icon {
-  font-size: 1.5rem;
+.btn {
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
+
+.btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.progress {
+  color: var(--vp-c-text-2);
+  font-size: 0.9rem;
+  margin-bottom: 0.75rem;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+.card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
+}
+
+.card-title {
+  font-weight: 800;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
+}
+
+.desc {
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+.box {
+  margin-top: 0.75rem;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
 }
 
 .box-title {
-  font-weight: 600;
-  font-size: 0.9rem;
+  font-weight: 800;
+  margin-bottom: 0.35rem;
+  color: var(--vp-c-text-1);
 }
 
-.box-content {
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
+.mono {
+  font-family: var(--vp-font-family-mono);
 }
 
-.login-status {
-  padding: 0.5rem;
-  border-radius: 6px;
-  text-align: center;
-  font-weight: 600;
-  font-size: 0.85rem;
-  background: #fef3c7;
-  color: #92400e;
-}
-
-.login-status.logged {
-  background: #d1fae5;
-  color: #065f46;
-}
-
-.action-btn {
-  width: 100%;
-  padding: 0.75rem;
-  border: none;
-  border-radius: 8px;
-  cursor: pointer;
-  font-weight: 600;
-  font-size: 0.9rem;
-  transition: all 0.2s ease;
-}
-
-.action-btn.login {
-  background: #3b82f6;
-  color: white;
-}
-
-.action-btn.transfer {
-  background: #22c55e;
-  color: white;
-}
-
-.action-btn.evil-btn {
-  background: #ef4444;
-  color: white;
-}
-
-.cookie-info {
-  background: white;
-  border-radius: 6px;
-  padding: 0.75rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.info-title {
-  font-size: 0.75rem;
-  font-weight: 600;
-  margin-bottom: 0.5rem;
-  color: var(--vp-c-text-2);
-}
-
-.cookie-item {
-  font-family: 'Courier New', monospace;
-  font-size: 0.75rem;
-  display: flex;
-  gap: 0.5rem;
-}
-
-.cookie-key {
-  color: #3b82f6;
-  font-weight: 600;
-}
-
-.cookie-value {
-  color: var(--vp-c-text-2);
-  word-break: break-all;
-}
-
-.scenario-arrow {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 2rem;
-  font-weight: 700;
-  color: var(--vp-c-text-2);
-  writing-mode: vertical-rl;
-  text-orientation: mixed;
-}
-
-.evil-content {
-  text-align: center;
-}
-
-.evil-content p {
-  font-size: 0.9rem;
-  margin-bottom: 1rem;
-}
-
-.evil-code {
-  background: #1e293b;
-  border-radius: 6px;
-  padding: 0.75rem;
-  margin-top: 1rem;
-  text-align: left;
-}
-
-.code-title {
-  font-size: 0.75rem;
-  font-weight: 600;
-  color: #94a3b8;
-  margin-bottom: 0.5rem;
-}
-
-.code-block {
-  font-family: 'Courier New', monospace;
-  font-size: 0.75rem;
-  color: #e2e8f0;
+.code {
   margin: 0;
-  white-space: pre-wrap;
-  word-break: break-all;
-}
-
-.attack-result {
-  margin-top: 1rem;
-}
-
-.result-box {
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  padding: 1rem;
-  border-radius: 8px;
-  font-weight: 600;
-}
-
-.result-box.danger {
-  background: rgba(239, 68, 68, 0.1);
-  border: 1px solid #ef4444;
-  color: #dc2626;
-}
-
-.result-box.warning {
-  background: rgba(245, 158, 11, 0.1);
-  border: 1px solid #f59e0b;
-  color: #d97706;
-}
-
-.result-icon {
-  font-size: 1.5rem;
-}
-
-.defense-mechanisms {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
   border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
 }
 
-.mechanisms-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.mechanism-tabs {
-  display: flex;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-  flex-wrap: wrap;
-}
-
-.tab-btn {
-  flex: 1;
-  min-width: 120px;
-  padding: 0.75rem 1rem;
-  border: 2px solid var(--vp-c-divider);
-  border-radius: 8px;
-  background: var(--vp-c-bg-soft);
-  cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  font-size: 0.9rem;
-}
-
-.tab-btn:hover {
-  border-color: var(--vp-c-brand);
-}
-
-.tab-btn.active {
-  background: var(--vp-c-brand);
-  color: white;
-  border-color: var(--vp-c-brand);
-}
-
-.tab-icon {
-  font-size: 1.2rem;
-}
-
-.mechanism-content {
-  animation: fadeIn 0.3s ease;
-}
-
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.mechanism-header {
-  margin-bottom: 1.5rem;
-}
-
-.header-title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
-}
-
-.header-subtitle {
-  font-size: 0.9rem;
-  color: var(--vp-c-text-2);
-}
-
-.mechanism-demo {
-  margin-bottom: 1.5rem;
-}
-
-.demo-flow {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-  margin-bottom: 1rem;
-}
-
-.flow-steps {
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-.flow-step {
-  display: flex;
-  gap: 0.75rem;
-  align-items: flex-start;
-}
-
-.step-number {
-  width: 28px;
-  height: 28px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  font-size: 0.85rem;
-  flex-shrink: 0;
-}
-
-.step-content {
-  flex: 1;
-  font-size: 0.85rem;
-  line-height: 1.5;
-  padding-top: 0.25rem;
-}
-
-.code-example {
-  background: #1e293b;
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.code-example .code-title {
-  font-size: 0.8rem;
-  font-weight: 600;
-  color: #94a3b8;
-  margin-bottom: 0.75rem;
-}
-
-.code-example .code-block {
-  font-size: 0.8rem;
-  line-height: 1.6;
-}
-
-.mechanism-pros-cons {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-  gap: 1rem;
-}
-
-.pros,
-.cons {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.list-title {
-  font-weight: 600;
-  font-size: 0.9rem;
-  margin-bottom: 0.75rem;
-}
-
-.pros ul,
-.cons ul {
+.list {
   margin: 0;
-  padding-left: 1.25rem;
+  padding-left: 1.2rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
 }
 
-.pros li,
-.cons li {
-  font-size: 0.85rem;
-  margin-bottom: 0.5rem;
-  line-height: 1.5;
-}
-
-.comparison-table {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.table-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-}
-
-thead th {
+.warn {
+  margin-top: 0.75rem;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+  border-radius: 8px;
   padding: 0.75rem;
-  text-align: left;
-  font-weight: 700;
-  font-size: 0.85rem;
-  border-bottom: 2px solid var(--vp-c-divider);
 }
 
-tbody td {
-  padding: 0.75rem;
-  border-bottom: 1px solid var(--vp-c-divider);
-  font-size: 0.85rem;
+.warn-title {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.25rem;
 }
 
-tbody tr:last-child td {
-  border-bottom: none;
+.warn-text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
 }
 
-@media (max-width: 768px) {
-  .attack-scenario {
-    grid-template-columns: 1fr;
-  }
-
-  .scenario-arrow {
-    writing-mode: horizontal-tb;
-    transform: rotate(90deg);
-  }
-
-  .mechanism-tabs {
-    flex-direction: column;
-  }
-
-  .mechanism-pros-cons {
+@media (max-width: 720px) {
+  .grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/JWTWorkflowDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/JWTWorkflowDemo.vue
index 822f83b..c5ce4e1 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/JWTWorkflowDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/JWTWorkflowDemo.vue
@@ -1,687 +1,361 @@
 <!--
   JWTWorkflowDemo.vue
-  JWT 工作流程演示
+  JWT 工作流程（手动推进，更贴近真实使用）
 -->
 <template>
   <div class="jwt-workflow-demo">
     <div class="header">
-      <div class="title">JWT 工作流程</div>
-      <div class="subtitle">JSON Web Token 的生成与验证</div>
+      <div class="title">🎫 JWT：生成 → 发送 → 验证 → 解析</div>
+      <div class="subtitle">
+        默认“手动推进”，不自动下一步；避免把演示误当成真实系统的安全边界。
+      </div>
     </div>
 
     <div class="controls">
-      <button
-        class="action-btn"
-        @click="generateToken"
-        :disabled="isProcessing"
-      >
-        <span class="btn-icon">🔑</span>
-        <span class="btn-text">生成 Token</span>
+      <button class="btn primary" @click="start" :disabled="step !== 0">
+        开始
       </button>
+      <button class="btn" @click="prev" :disabled="step <= 1">上一步</button>
       <button
-        class="action-btn"
-        @click="verifyToken"
-        :disabled="!generatedToken || isProcessing"
+        class="btn primary"
+        @click="next"
+        :disabled="step === 0 || step >= maxStep"
       >
-        <span class="btn-icon">✅</span>
-        <span class="btn-text">验证 Token</span>
-      </button>
-      <button
-        class="action-btn"
-        @click="decodeToken"
-        :disabled="!generatedToken || isProcessing"
-      >
-        <span class="btn-icon">🔓</span>
-        <span class="btn-text">解析 Payload</span>
-      </button>
-      <button
-        class="action-btn reset"
-        @click="resetDemo"
-        :disabled="isProcessing"
-      >
-        <span class="btn-icon">🔄</span>
-        <span class="btn-text">重置</span>
+        下一步
       </button>
+      <button class="btn" @click="reset">重置</button>
     </div>
 
-    <div class="demo-area">
-      <div class="user-info">
-        <div class="info-title">用户信息</div>
-        <div class="info-content">
-          <div class="info-row">
-            <span class="info-key">用户 ID:</span>
-            <span class="info-value">123</span>
-          </div>
-          <div class="info-row">
-            <span class="info-key">用户名:</span>
-            <span class="info-value">alice</span>
-          </div>
-          <div class="info-row">
-            <span class="info-key">角色:</span>
-            <span class="info-value">admin</span>
-          </div>
+    <div v-if="step > 0" class="progress">
+      Step {{ step }} / {{ maxStep }} · {{ steps[step - 1]?.title }}
+    </div>
+
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">用户声明（Payload 示例）</div>
+        <pre class="code"><code>{{ payloadJson }}</code></pre>
+        <div class="hint">
+          注意：JWT 的 payload 只是 Base64Url
+          编码，任何人都能解码，所以不要放密码、手机号等敏感数据。
         </div>
       </div>
 
-      <div class="token-display" v-if="generatedToken">
-        <div class="token-title">生成的 JWT</div>
-        <div class="token-parts">
-          <div class="token-part header" @click="showPart = 'header'">
+      <div class="card">
+        <div class="card-title">JWT Token（示意）</div>
+        <div class="token">
+          <div class="part" :class="{ active: step >= 1 }">
             <div class="part-label">Header</div>
-            <div class="part-content">{{ tokenParts.header }}</div>
+            <code class="mono">{{ step >= 1 ? headerB64 : '...' }}</code>
           </div>
-          <div class="token-divider">.</div>
-          <div class="token-part payload" @click="showPart = 'payload'">
+          <div class="dot">.</div>
+          <div class="part" :class="{ active: step >= 2 }">
             <div class="part-label">Payload</div>
-            <div class="part-content">{{ tokenParts.payload }}</div>
+            <code class="mono">{{ step >= 2 ? payloadB64 : '...' }}</code>
           </div>
-          <div class="token-divider">.</div>
-          <div class="token-part signature" @click="showPart = 'signature'">
+          <div class="dot">.</div>
+          <div class="part" :class="{ active: step >= 3 }">
             <div class="part-label">Signature</div>
-            <div class="part-content">{{ tokenParts.signature }}</div>
+            <code class="mono">{{ step >= 3 ? signatureB64 : '...' }}</code>
           </div>
         </div>
 
-        <div class="token-full" v-if="showFull">
-          <div class="full-title">完整 Token</div>
-          <div class="full-content">{{ generatedToken }}</div>
+        <div class="mono-box" v-if="step >= 4">
+          <div class="mono-label">完整 Token</div>
+          <code class="mono">{{ token }}</code>
+          <button class="copy" @click="copy(token)">
+            {{ copied ? '已复制' : '复制 Token' }}
+          </button>
         </div>
 
-        <button class="toggle-btn" @click="showFull = !showFull">
-          {{ showFull ? '隐藏' : '显示' }}完整 Token
-        </button>
-      </div>
-
-      <div class="part-detail" v-if="showPart && partDetail">
-        <div class="detail-title">
-          {{
-            showPart === 'header'
-              ? 'Header'
-              : showPart === 'payload'
-                ? 'Payload'
-                : 'Signature'
-          }}
-          详情
-        </div>
-        <div class="detail-content">
-          <pre class="detail-json">{{ partDetail }}</pre>
-        </div>
-      </div>
-
-      <div class="result-box" v-if="result" :class="result.type">
-        <div class="result-icon">{{ result.icon }}</div>
-        <div class="result-text">{{ result.text }}</div>
-      </div>
-    </div>
-
-    <div class="jwt-structure">
-      <div class="structure-title">JWT 结构</div>
-      <div class="structure-diagram">
-        <div class="diagram-part">
-          <div class="part-name">Header</div>
-          <div class="part-desc">算法信息</div>
-          <div class="part-example">{"alg": "HS256", "typ": "JWT"}</div>
-        </div>
-        <div class="diagram-plus">+</div>
-        <div class="diagram-part">
-          <div class="part-name">Payload</div>
-          <div class="part-desc">用户信息</div>
-          <div class="part-example">{"user_id": 123, "role": "admin"}</div>
-        </div>
-        <div class="diagram-plus">+</div>
-        <div class="diagram-part">
-          <div class="part-name">Signature</div>
-          <div class="part-desc">签名（防篡改）</div>
-          <div class="part-example">
-            HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),
-            secret)
-          </div>
+        <div class="mono-box" v-if="step >= 5">
+          <div class="mono-label">请求头示例</div>
+          <code class="mono">Authorization: Bearer {{ token }}</code>
         </div>
       </div>
     </div>
 
-    <div class="info-cards">
-      <div class="info-card pros">
-        <div class="card-icon">✅</div>
-        <div class="card-title">优点</div>
-        <ul class="card-list">
-          <li>无状态，服务端不存储</li>
-          <li>易于横向扩展</li>
-          <li>跨域友好</li>
-          <li>移动端友好</li>
-        </ul>
-      </div>
-
-      <div class="info-card cons">
-        <div class="card-icon">⚠️</div>
-        <div class="card-title">缺点</div>
-        <ul class="card-list">
-          <li>无法主动注销</li>
-          <li>Payload 可见，不能存敏感信息</li>
-          <li>Token 过大，每次请求都要带上</li>
-        </ul>
+    <div class="card">
+      <div class="card-title">{{ steps[step - 1]?.title || '流程说明' }}</div>
+      <div class="desc">{{ steps[step - 1]?.desc }}</div>
+      <div v-if="steps[step - 1]?.warn" class="warn">
+        <div class="warn-title">注意</div>
+        <div class="warn-text">{{ steps[step - 1]?.warn }}</div>
       </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const isProcessing = ref(false)
-const generatedToken = ref('')
-const showFull = ref(false)
-const showPart = ref(null)
-const result = ref(null)
+const maxStep = 6
+const step = ref(0)
+const copied = ref(false)
 
-const tokenParts = ref({
-  header: '',
-  payload: '',
-  signature: ''
-})
+const headerObj = { alg: 'HS256', typ: 'JWT' }
+const payloadObj = computed(() => ({
+  user_id: 123,
+  username: 'alice',
+  role: 'admin',
+  iat: Math.floor(Date.now() / 1000),
+  exp: Math.floor(Date.now() / 1000) + 3600
+}))
 
-const partDetail = computed(() => {
-  if (showPart.value === 'header') {
-    return JSON.stringify({ alg: 'HS256', typ: 'JWT' }, null, 2)
-  } else if (showPart.value === 'payload') {
-    return JSON.stringify(
-      {
-        user_id: 123,
-        username: 'alice',
-        role: 'admin',
-        iat: Math.floor(Date.now() / 1000),
-        exp: Math.floor(Date.now() / 1000) + 3600
-      },
-      null,
-      2
-    )
-  } else if (showPart.value === 'signature') {
-    return 'HMACSHA256(\n  base64UrlEncode(header) + "." + base64UrlEncode(payload),\n  your-secret-key\n)'
+const payloadJson = computed(() => JSON.stringify(payloadObj.value, null, 2))
+const headerB64 = computed(() => btoa(JSON.stringify(headerObj)))
+const payloadB64 = computed(() => btoa(JSON.stringify(payloadObj.value)))
+const signatureB64 = computed(() =>
+  btoa(`${headerB64.value}.${payloadB64.value}.your-secret-key`)
+)
+const token = computed(
+  () => `${headerB64.value}.${payloadB64.value}.${signatureB64.value}`
+)
+
+const steps = [
+  {
+    title: '1) 生成 Header',
+    desc: 'Header 描述使用的算法与 token 类型（JWT）。'
+  },
+  {
+    title: '2) 生成 Payload',
+    desc: 'Payload 放业务声明（claims）。它可被解码，所以不要放敏感信息。'
+  },
+  {
+    title: '3) 生成 Signature',
+    desc: 'Signature 用密钥对 header.payload 做签名，用来防篡改。',
+    warn: '只有“签名校验”能保证 payload 未被改过；Base64 不是加密。'
+  },
+  {
+    title: '4) 拼接 Token',
+    desc: '把三段用 “.” 连接：header.payload.signature。'
+  },
+  {
+    title: '5) 客户端发送请求',
+    desc: '通常放在 Authorization: Bearer <token>。'
+  },
+  {
+    title: '6) 服务端验证与授权',
+    desc: '服务端校验签名与过期时间，再按 role/权限做授权判断。',
+    warn: 'JWT 无法“立刻全局注销”：常用解法是短 access token + refresh token + 黑名单/版本号。'
   }
-  return null
-})
+]
 
-const generateToken = async () => {
-  isProcessing.value = true
-  result.value = null
-
-  // 模拟生成 JWT
-  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
-  const payload = btoa(
-    JSON.stringify({
-      user_id: 123,
-      username: 'alice',
-      role: 'admin',
-      iat: Math.floor(Date.now() / 1000),
-      exp: Math.floor(Date.now() / 1000) + 3600
-    })
-  )
-  const signature = btoa(`${header}.${payload}.your-secret-key`)
-
-  tokenParts.value = {
-    header: header.substring(0, 20) + '...',
-    payload: payload.substring(0, 20) + '...',
-    signature: signature.substring(0, 20) + '...'
-  }
-
-  generatedToken.value = `${header}.${payload}.${signature}`
-
-  await delay(800)
-
-  result.value = {
-    type: 'success',
-    icon: '✅',
-    text: 'Token 生成成功！有效期 1 小时'
-  }
-
-  isProcessing.value = false
+const start = () => {
+  step.value = 1
 }
 
-const verifyToken = async () => {
-  isProcessing.value = true
+const next = () => {
+  step.value = Math.min(maxStep, step.value + 1)
+}
 
-  await delay(800)
+const prev = () => {
+  step.value = Math.max(1, step.value - 1)
+}
 
-  // 模拟验证
-  const isValid = Math.random() > 0.2
+const reset = () => {
+  step.value = 0
+  copied.value = false
+}
 
-  result.value = {
-    type: isValid ? 'success' : 'error',
-    icon: isValid ? '✅' : '❌',
-    text: isValid ? 'Token 验证通过！签名有效' : 'Token 验证失败：签名无效'
+const copy = async (text) => {
+  try {
+    await navigator.clipboard.writeText(text)
+    copied.value = true
+    setTimeout(() => {
+      copied.value = false
+    }, 800)
+  } catch {
+    copied.value = false
   }
-
-  isProcessing.value = false
 }
-
-const decodeToken = async () => {
-  isProcessing.value = true
-
-  await delay(600)
-
-  showPart.value = 'payload'
-
-  result.value = {
-    type: 'info',
-    icon: '🔓',
-    text: 'Payload 已解析（Base64 可解码，不要存敏感信息！）'
-  }
-
-  isProcessing.value = false
-}
-
-const resetDemo = () => {
-  generatedToken.value = ''
-  tokenParts.value = { header: '', payload: '', signature: '' }
-  showFull.value = false
-  showPart.value = null
-  result.value = null
-}
-
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 </script>
 
 <style scoped>
 .jwt-workflow-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
 .controls {
   display: flex;
-  gap: 0.75rem;
-  margin-bottom: 1.5rem;
-  flex-wrap: wrap;
-}
-
-.action-btn {
-  flex: 1;
-  min-width: 120px;
-  padding: 0.75rem 1rem;
-  border: none;
-  border-radius: 8px;
-  background: var(--vp-c-brand);
-  color: white;
-  cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
-  align-items: center;
-  justify-content: center;
   gap: 0.5rem;
-  font-weight: 600;
-  font-size: 0.9rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.action-btn:disabled {
+.btn {
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
+
+.btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.btn:disabled {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
-.action-btn:hover:not(:disabled) {
-  background: #2563eb;
-}
-
-.action-btn.reset {
-  background: #64748b;
-}
-
-.action-btn.reset:hover:not(:disabled) {
-  background: #475569;
-}
-
-.btn-icon {
-  font-size: 1.2rem;
-}
-
-.demo-area {
-  display: flex;
-  flex-direction: column;
-  gap: 1.5rem;
-  margin-bottom: 1.5rem;
-}
-
-.user-info {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.info-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.info-content {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.info-row {
-  display: flex;
-  gap: 0.75rem;
-  padding: 0.5rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 6px;
-}
-
-.info-key {
-  font-weight: 600;
-  color: var(--vp-c-brand);
-  min-width: 80px;
-}
-
-.info-value {
-  color: var(--vp-c-text-1);
-  font-family: 'Courier New', monospace;
-}
-
-.token-display {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.token-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.token-parts {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.25rem;
-  margin-bottom: 1rem;
-}
-
-.token-part {
-  flex: 1;
-  min-width: 100px;
-  padding: 0.75rem;
-  border-radius: 8px;
-  border: 2px solid var(--vp-c-divider);
-  cursor: pointer;
-  transition: all 0.2s ease;
-}
-
-.token-part:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
-}
-
-.token-part.header {
-  background: rgba(59, 130, 246, 0.1);
-  border-color: #3b82f6;
-}
-
-.token-part.payload {
-  background: rgba(168, 85, 247, 0.1);
-  border-color: #a855f7;
-}
-
-.token-part.signature {
-  background: rgba(34, 197, 94, 0.1);
-  border-color: #22c55e;
-}
-
-.part-label {
-  font-weight: 700;
-  font-size: 0.75rem;
-  margin-bottom: 0.5rem;
-  text-transform: uppercase;
-}
-
-.part-content {
-  font-family: 'Courier New', monospace;
-  font-size: 0.7rem;
+.progress {
   color: var(--vp-c-text-2);
-  word-break: break-all;
-}
-
-.token-divider {
-  display: flex;
-  align-items: center;
-  font-size: 1.5rem;
-  font-weight: 700;
-  color: var(--vp-c-text-2);
-}
-
-.token-full {
-  margin-bottom: 1rem;
-  padding: 0.75rem;
-  background: #1e293b;
-  border-radius: 6px;
-}
-
-.full-title {
-  font-size: 0.75rem;
-  font-weight: 600;
-  color: #94a3b8;
-  margin-bottom: 0.5rem;
-}
-
-.full-content {
-  font-family: 'Courier New', monospace;
-  font-size: 0.7rem;
-  color: #e2e8f0;
-  word-break: break-all;
-  line-height: 1.5;
-}
-
-.toggle-btn {
-  padding: 0.5rem 1rem;
-  border: 1px solid var(--vp-c-divider);
-  border-radius: 6px;
-  background: var(--vp-c-bg-soft);
-  cursor: pointer;
-  font-size: 0.85rem;
-  transition: all 0.2s ease;
-}
-
-.toggle-btn:hover {
-  background: var(--vp-c-brand);
-  color: white;
-  border-color: var(--vp-c-brand);
-}
-
-.part-detail {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.detail-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.detail-content {
-  background: #1e293b;
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.detail-json {
-  font-family: 'Courier New', monospace;
-  font-size: 0.85rem;
-  color: #e2e8f0;
-  line-height: 1.6;
-  margin: 0;
-  white-space: pre-wrap;
-  word-break: break-all;
-}
-
-.result-box {
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  padding: 1rem;
-  border-radius: 8px;
-  font-weight: 600;
-}
-
-.result-box.success {
-  background: rgba(34, 197, 94, 0.1);
-  border: 1px solid #22c55e;
-  color: #16a34a;
-}
-
-.result-box.error {
-  background: rgba(239, 68, 68, 0.1);
-  border: 1px solid #ef4444;
-  color: #dc2626;
-}
-
-.result-box.info {
-  background: rgba(59, 130, 246, 0.1);
-  border: 1px solid #3b82f6;
-  color: #2563eb;
-}
-
-.result-icon {
-  font-size: 1.5rem;
-}
-
-.jwt-structure {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.structure-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.structure-diagram {
-  display: flex;
-  align-items: stretch;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-}
-
-.diagram-part {
-  flex: 1;
-  min-width: 180px;
-  padding: 1rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.part-name {
-  font-weight: 700;
   font-size: 0.9rem;
-  margin-bottom: 0.5rem;
-  color: var(--vp-c-brand);
-}
-
-.part-desc {
-  font-size: 0.8rem;
-  color: var(--vp-c-text-2);
   margin-bottom: 0.75rem;
 }
 
-.part-example {
-  font-family: 'Courier New', monospace;
-  font-size: 0.75rem;
-  color: var(--vp-c-text-1);
-  background: white;
-  padding: 0.5rem;
-  border-radius: 6px;
-  border: 1px solid var(--vp-c-divider);
-  word-break: break-all;
-}
-
-.diagram-plus {
-  display: flex;
-  align-items: center;
-  font-size: 2rem;
-  font-weight: 700;
-  color: var(--vp-c-text-2);
-}
-
-.info-cards {
+.grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  grid-template-columns: 1fr 1fr;
   gap: 1rem;
+  margin-bottom: 1rem;
 }
 
-.info-card {
+.card {
   background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
   border: 1px solid var(--vp-c-divider);
-}
-
-.card-icon {
-  font-size: 2rem;
-  margin-bottom: 0.75rem;
+  border-radius: 8px;
+  padding: 1rem;
 }
 
 .card-title {
-  font-weight: 700;
-  font-size: 1rem;
+  font-weight: 800;
   margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
 }
 
-.card-list {
+.code {
   margin: 0;
-  padding-left: 1.25rem;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
 }
 
-.card-list li {
-  margin-bottom: 0.5rem;
+.hint {
+  margin-top: 0.75rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+  font-size: 0.9rem;
+}
+
+.token {
+  display: flex;
+  align-items: stretch;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.part {
+  flex: 1;
+  min-width: 220px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
+  opacity: 0.6;
+}
+
+.part.active {
+  opacity: 1;
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+}
+
+.part-label {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.35rem;
+}
+
+.dot {
+  display: none;
+}
+
+.mono {
+  font-family: var(--vp-font-family-mono);
   font-size: 0.85rem;
-  line-height: 1.5;
+  color: var(--vp-c-text-1);
+  word-break: break-all;
 }
 
-.info-card.pros .card-list li {
-  color: #16a34a;
+.mono-box {
+  margin-top: 0.75rem;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
 }
 
-.info-card.cons .card-list li {
-  color: #dc2626;
+.mono-label {
+  color: var(--vp-c-text-2);
+  font-size: 0.8rem;
+  margin-bottom: 0.35rem;
 }
 
-@media (max-width: 768px) {
-  .structure-diagram {
-    flex-direction: column;
-  }
+.copy {
+  margin-top: 0.5rem;
+  padding: 0.35rem 0.6rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
 
-  .diagram-plus {
-    transform: rotate(90deg);
-  }
+.desc {
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
 
-  .info-cards {
+.warn {
+  margin-top: 0.75rem;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+
+.warn-title {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.25rem;
+}
+
+.warn-text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+@media (max-width: 720px) {
+  .grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/OAuth2FlowDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/OAuth2FlowDemo.vue
index 2732154..f9139c2 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/OAuth2FlowDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/OAuth2FlowDemo.vue
@@ -1,673 +1,346 @@
 <!--
   OAuth2FlowDemo.vue
-  OAuth 2.0 授权流程演示
+  OAuth2 / OIDC 授权码流程（手动推进，更贴近真实接入）
 -->
 <template>
-  <div class="oauth2-flow-demo">
+  <div class="oauth2-demo">
     <div class="header">
-      <div class="title">OAuth 2.0 授权码流程</div>
-      <div class="subtitle">第三方登录（如微信登录）的完整流程</div>
+      <div class="title">🔑 OAuth2：第三方登录（授权码流程）</div>
+      <div class="subtitle">
+        用最常见的 Authorization Code Flow（建议配合
+        PKCE）。默认手动推进，不自动下一步。
+      </div>
     </div>
 
     <div class="controls">
-      <button
-        class="action-btn"
-        @click="startFlow"
-        :disabled="isProcessing || currentStep > 0"
-      >
-        <span class="btn-icon">🚀</span>
-        <span class="btn-text">开始授权流程</span>
+      <button class="btn primary" @click="start" :disabled="step !== 0">
+        开始
       </button>
+      <button class="btn" @click="prev" :disabled="step <= 1">上一步</button>
       <button
-        class="action-btn"
-        @click="nextStep"
-        :disabled="isProcessing || currentStep === 0 || currentStep >= maxSteps"
+        class="btn primary"
+        @click="next"
+        :disabled="step === 0 || step >= maxStep"
       >
-        <span class="btn-icon">➡️</span>
-        <span class="btn-text">下一步</span>
+        下一步
       </button>
-      <button
-        class="action-btn reset"
-        @click="resetFlow"
-        :disabled="isProcessing"
-      >
-        <span class="btn-icon">🔄</span>
-        <span class="btn-text">重置</span>
+      <button class="btn" @click="reset">重置</button>
+      <button class="btn" @click="copy(currentCmd)" :disabled="!currentCmd">
+        {{ copied ? '已复制' : '复制命令' }}
       </button>
     </div>
 
-    <div class="flow-visualization">
-      <div class="actors">
-        <div class="actor user" :class="{ active: isUserActive }">
-          <div class="actor-icon">👤</div>
-          <div class="actor-label">用户</div>
-        </div>
+    <div v-if="step > 0" class="progress">
+      Step {{ step }} / {{ maxStep }} · {{ steps[step - 1]?.title }}
+    </div>
 
-        <div class="actor client" :class="{ active: isClientActive }">
-          <div class="actor-icon">🌐</div>
-          <div class="actor-label">第三方应用</div>
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">角色</div>
+        <div class="role">
+          <div class="pill">Client（你的应用）</div>
+          <div class="pill">Authorization Server（微信/Google 等）</div>
+          <div class="pill">Resource Server（你的 API）</div>
         </div>
-
-        <div class="actor auth-server" :class="{ active: isAuthServerActive }">
-          <div class="actor-icon">🔐</div>
-          <div class="actor-label">授权服务器</div>
-          <div class="actor-sub">微信/Google</div>
-        </div>
-
-        <div
-          class="actor resource-server"
-          :class="{ active: isResourceServerActive }"
-        >
-          <div class="actor-icon">📊</div>
-          <div class="actor-label">资源服务器</div>
-          <div class="actor-sub">用户信息 API</div>
+        <div class="desc">
+          OAuth2
+          的核心：<strong>你的应用不再保存用户在第三方的密码</strong>，而是拿到授权码/令牌后去换取用户信息。
         </div>
       </div>
 
-      <div class="current-action" v-if="currentAction">
-        <div class="action-icon">{{ currentAction.icon }}</div>
-        <div class="action-text">{{ currentAction.text }}</div>
-        <div class="action-detail" v-if="currentAction.detail">
-          {{ currentAction.detail }}
-        </div>
-      </div>
-
-      <div class="data-exchange" v-if="currentDataExchange">
-        <div class="exchange-title">数据交换</div>
-        <div class="exchange-content">
-          <div
-            class="exchange-item"
-            v-for="(item, index) in currentDataExchange"
-            :key="index"
-          >
-            <span class="exchange-label">{{ item.label }}:</span>
-            <span class="exchange-value">{{ item.value }}</span>
-          </div>
+      <div class="card">
+        <div class="card-title">本步要做什么</div>
+        <div class="desc">{{ steps[step - 1]?.desc || '点击开始' }}</div>
+        <div v-if="steps[step - 1]?.warn" class="warn">
+          <div class="warn-title">注意</div>
+          <div class="warn-text">{{ steps[step - 1]?.warn }}</div>
         </div>
       </div>
     </div>
 
-    <div class="flow-steps">
-      <div class="steps-title">流程步骤</div>
-      <div class="steps-list">
-        <div
-          v-for="(step, index) in flowSteps"
-          :key="index"
-          class="step-item"
-          :class="{
-            active: currentStep === index + 1,
-            completed: currentStep > index + 1,
-            current: currentStep === index + 1
-          }"
-        >
-          <div class="step-number">{{ index + 1 }}</div>
-          <div class="step-content">
-            <div class="step-title">{{ step.title }}</div>
-            <div class="step-desc">{{ step.desc }}</div>
-          </div>
-        </div>
+    <div class="card">
+      <div class="card-title">请求/命令示例（可照抄）</div>
+      <pre
+        class="code"
+      ><code>{{ currentCmd || '（点击开始后显示）' }}</code></pre>
+      <div class="hint">
+        这是“示例请求”，不是你电脑上真实发出去的请求；你可以把参数替换成自己的
+        client_id / redirect_uri。
       </div>
     </div>
 
-    <div class="security-notes">
-      <div class="notes-title">安全要点</div>
-      <div class="notes-list">
-        <div class="note-item">
-          <div class="note-icon">🔒</div>
-          <div class="note-content">
-            <div class="note-title">code 只能用一次</div>
-            <div class="note-text">授权码使用后立即失效，防止截获重放</div>
-          </div>
-        </div>
-        <div class="note-item">
-          <div class="note-icon">🎲</div>
-          <div class="note-content">
-            <div class="note-title">state 防 CSRF</div>
-            <div class="note-text">
-              生成随机字符串，回调时验证，防止恶意网站伪造
-            </div>
-          </div>
-        </div>
-        <div class="note-item">
-          <div class="note-icon">🔗</div>
-          <div class="note-content">
-            <div class="note-title">redirect_uri 必须匹配</div>
-            <div class="note-text">提前在授权服务器注册，防止重定向攻击</div>
-          </div>
-        </div>
-      </div>
-    </div>
-
-    <div class="participants-table">
-      <div class="table-title">OAuth 2.0 核心角色</div>
-      <table>
-        <thead>
-          <tr>
-            <th>角色</th>
-            <th>说明</th>
-            <th>例子</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td><strong>Resource Owner</strong></td>
-            <td>资源所有者（用户）</td>
-            <td>你</td>
-          </tr>
-          <tr>
-            <td><strong>Client</strong></td>
-            <td>第三方应用</td>
-            <td>某个网站</td>
-          </tr>
-          <tr>
-            <td><strong>Authorization Server</strong></td>
-            <td>授权服务器</td>
-            <td>微信、Google</td>
-          </tr>
-          <tr>
-            <td><strong>Resource Server</strong></td>
-            <td>资源服务器</td>
-            <td>微信的用户信息 API</td>
-          </tr>
-        </tbody>
-      </table>
+    <div class="card">
+      <div class="card-title">你真正需要记住的 4 件事</div>
+      <ul class="list">
+        <li>
+          <strong>redirect_uri 必须白名单：</strong>避免被人把 code
+          劫持到自己的站。
+        </li>
+        <li><strong>state 必须校验：</strong>防 CSRF（登录也会被 CSRF）。</li>
+        <li><strong>code 只能用一次且很快过期：</strong>泄露影响有限。</li>
+        <li>
+          <strong>access token 要短 + refresh token 要保护：</strong>refresh
+          token 更像“长期钥匙”。
+        </li>
+      </ul>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const currentStep = ref(0)
-const isProcessing = ref(false)
-const maxSteps = 5
+const maxStep = 6
+const step = ref(0)
+const copied = ref(false)
 
-const currentAction = ref(null)
-const currentDataExchange = ref(null)
+const params = {
+  clientId: 'your_client_id',
+  redirectUri: 'https://your.app/callback',
+  scope: 'openid profile email',
+  state: 'random_state_123',
+  code: 'auth_code_xyz',
+  codeVerifier: 'pkce_verifier_...',
+  codeChallenge: 'pkce_challenge_...'
+}
 
-const flowSteps = [
+const steps = [
   {
-    title: '用户点击"使用微信登录"',
-    desc: '第三方应用重定向到微信授权页面'
+    title: '1) 跳转到授权页',
+    desc: '你的应用把用户重定向到授权服务器，让用户登录并授权。',
+    warn: 'redirect_uri 必须白名单；state 用于防 CSRF。'
   },
   {
-    title: '用户扫码并同意授权',
-    desc: '微信重定向回第三方应用，携带授权码 code'
+    title: '2) 用户授权',
+    desc: '用户在第三方确认“允许此应用读取基本信息”。（这一步发生在第三方页面）'
   },
   {
-    title: '后端用 code 换取 access_token',
-    desc: '第三方应用后端调用微信 API，使用 code 换取 token'
+    title: '3) 带 code 回调',
+    desc: '授权服务器把用户带回 redirect_uri，并附上一次性的授权码 code。'
   },
   {
-    title: '用 access_token 获取用户信息',
-    desc: '调用微信用户信息 API，获取用户数据'
+    title: '4) 用 code 换 token',
+    desc: '你的后端（或移动端 + PKCE）调用 token endpoint，把 code 换成 access token。'
   },
   {
-    title: '创建或更新本地用户',
-    desc: '第三方应用创建本地用户，生成本系统的 JWT'
+    title: '5) 用 token 拉取用户信息',
+    desc: '携带 access token 请求 userinfo（或你自己业务的资源服务）。'
+  },
+  {
+    title: '6) 建立你自己的登录态',
+    desc: 'OAuth2 只解决“第三方授权”，你的系统还要创建自己的 session/JWT（并做授权）。',
+    warn: '不要把第三方 access token 当作你系统的权限 token；两者用途不同。'
   }
 ]
 
-const stepActions = {
-  1: {
-    icon: '👆',
-    text: '用户点击授权按钮',
-    detail: '重定向到微信授权页面',
-    dataExchange: [
-      { label: 'URL', value: 'open.weixin.qq.com/connect/qrconnect' },
-      { label: 'appid', value: 'wx1234567890' },
-      { label: 'redirect_uri', value: 'https://yourapp.com/callback' },
-      { label: 'response_type', value: 'code' },
-      { label: 'state', value: 'random_state_string' }
-    ],
-    activeActors: ['client', 'auth-server']
-  },
-  2: {
-    icon: '✅',
-    text: '用户同意授权',
-    detail: '微信重定向回第三方应用',
-    dataExchange: [
-      { label: 'Callback URL', value: 'https://yourapp.com/callback' },
-      { label: 'code', value: 'AUTHORIZATION_CODE' },
-      { label: 'state', value: 'random_state_string' }
-    ],
-    activeActors: ['user', 'auth-server', 'client']
-  },
-  3: {
-    icon: '🔄',
-    text: '后端交换 Token',
-    detail: '使用 code 换取 access_token',
-    dataExchange: [
-      { label: 'POST', value: 'api.weixin.qq.com/sns/oauth2/access_token' },
-      { label: 'appid', value: 'wx1234567890' },
-      { label: 'secret', value: '***' },
-      { label: 'code', value: 'AUTHORIZATION_CODE' },
-      { label: 'grant_type', value: 'authorization_code' }
-    ],
-    activeActors: ['client', 'auth-server']
-  },
-  4: {
-    icon: '📊',
-    text: '获取用户信息',
-    detail: '使用 access_token 调用用户信息 API',
-    dataExchange: [
-      { label: 'GET', value: 'api.weixin.qq.com/sns/userinfo' },
-      { label: 'access_token', value: 'ACCESS_TOKEN' },
-      { label: 'openid', value: 'USER_OPENID' },
-      { label: '返回', value: '{ nickname, headimgurl, ... }' }
-    ],
-    activeActors: ['client', 'resource-server']
-  },
-  5: {
-    icon: '🎉',
-    text: '创建本地用户',
-    detail: '生成第三方应用的 JWT Token',
-    dataExchange: [
-      { label: '操作', value: '创建或更新本地用户' },
-      { label: '生成', value: '本地 JWT Token' },
-      { label: '返回', value: '{ token, user_info }' }
-    ],
-    activeActors: ['client']
+const currentCmd = computed(() => {
+  if (step.value === 0) return ''
+  if (step.value === 1) {
+    return `GET https://auth.server/authorize?response_type=code&client_id=${params.clientId}&redirect_uri=${encodeURIComponent(
+      params.redirectUri
+    )}&scope=${encodeURIComponent(params.scope)}&state=${params.state}&code_challenge=${params.codeChallenge}&code_challenge_method=S256`
+  }
+  if (step.value === 2) {
+    return `（用户在授权页点击“同意/授权”）`
+  }
+  if (step.value === 3) {
+    return `302 ${params.redirectUri}?code=${params.code}&state=${params.state}`
+  }
+  if (step.value === 4) {
+    return `POST https://auth.server/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=${params.code}&
+redirect_uri=${encodeURIComponent(params.redirectUri)}&
+client_id=${params.clientId}&
+code_verifier=${params.codeVerifier}`
+  }
+  if (step.value === 5) {
+    return `GET https://auth.server/userinfo
+Authorization: Bearer <access_token>`
+  }
+  return `你的后端：
+1) 读取 userinfo（拿到第三方 user_id）
+2) 在你系统里创建/绑定用户
+3) 返回你自己的 session cookie 或 JWT`
+})
+
+const start = () => {
+  step.value = 1
+}
+
+const next = () => {
+  step.value = Math.min(maxStep, step.value + 1)
+}
+
+const prev = () => {
+  step.value = Math.max(1, step.value - 1)
+}
+
+const reset = () => {
+  step.value = 0
+  copied.value = false
+}
+
+const copy = async (text) => {
+  try {
+    await navigator.clipboard.writeText(text)
+    copied.value = true
+    setTimeout(() => {
+      copied.value = false
+    }, 800)
+  } catch {
+    copied.value = false
   }
 }
-
-const isUserActive = computed(() =>
-  stepActions[currentStep.value]?.activeActors.includes('user')
-)
-const isClientActive = computed(() =>
-  stepActions[currentStep.value]?.activeActors.includes('client')
-)
-const isAuthServerActive = computed(() =>
-  stepActions[currentStep.value]?.activeActors.includes('auth-server')
-)
-const isResourceServerActive = computed(() =>
-  stepActions[currentStep.value]?.activeActors.includes('resource-server')
-)
-
-const startFlow = async () => {
-  isProcessing.value = true
-  currentStep.value = 1
-  await executeStep(1)
-  isProcessing.value = false
-}
-
-const nextStep = async () => {
-  if (currentStep.value >= maxSteps) return
-
-  isProcessing.value = true
-  currentStep.value++
-  await executeStep(currentStep.value)
-  isProcessing.value = false
-}
-
-const executeStep = async (step) => {
-  const action = stepActions[step]
-  currentAction.value = {
-    icon: action.icon,
-    text: action.text,
-    detail: action.detail
-  }
-  currentDataExchange.value = action.dataExchange
-
-  await delay(1500)
-}
-
-const resetFlow = () => {
-  currentStep.value = 0
-  currentAction.value = null
-  currentDataExchange.value = null
-}
-
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 </script>
 
 <style scoped>
-.oauth2-flow-demo {
+.oauth2-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
 .controls {
   display: flex;
-  gap: 0.75rem;
-  margin-bottom: 1.5rem;
-  flex-wrap: wrap;
-}
-
-.action-btn {
-  flex: 1;
-  min-width: 120px;
-  padding: 0.75rem 1rem;
-  border: none;
-  border-radius: 8px;
-  background: var(--vp-c-brand);
-  color: white;
-  cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
-  align-items: center;
-  justify-content: center;
   gap: 0.5rem;
-  font-weight: 600;
-  font-size: 0.9rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.action-btn:disabled {
+.btn {
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
+
+.btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.btn:disabled {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
-.action-btn:hover:not(:disabled) {
-  background: #2563eb;
-}
-
-.action-btn.reset {
-  background: #64748b;
-}
-
-.action-btn.reset:hover:not(:disabled) {
-  background: #475569;
-}
-
-.btn-icon {
-  font-size: 1.2rem;
-}
-
-.flow-visualization {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.actors {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
-  gap: 1rem;
-  margin-bottom: 1.5rem;
-}
-
-.actor {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  padding: 1rem;
-  border-radius: 10px;
-  border: 2px solid var(--vp-c-divider);
-  background: var(--vp-c-bg-soft);
-  transition: all 0.3s ease;
-  opacity: 0.5;
-}
-
-.actor.active {
-  opacity: 1;
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-  transform: scale(1.05);
-}
-
-.actor-icon {
-  font-size: 2rem;
-  margin-bottom: 0.5rem;
-}
-
-.actor-label {
-  font-weight: 600;
+.progress {
+  color: var(--vp-c-text-2);
   font-size: 0.9rem;
-  margin-bottom: 0.25rem;
-}
-
-.actor-sub {
-  font-size: 0.75rem;
-  color: var(--vp-c-text-2);
-}
-
-.current-action {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-  margin-bottom: 1rem;
-  border: 2px solid var(--vp-c-brand);
-}
-
-.action-icon {
-  font-size: 2rem;
-  margin-bottom: 0.5rem;
-}
-
-.action-text {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 0.25rem;
-}
-
-.action-detail {
-  font-size: 0.85rem;
-  color: var(--vp-c-text-2);
-}
-
-.data-exchange {
-  background: #1e293b;
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.exchange-title {
-  font-size: 0.75rem;
-  font-weight: 600;
-  color: #94a3b8;
   margin-bottom: 0.75rem;
 }
 
-.exchange-content {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.exchange-item {
-  display: flex;
-  gap: 0.5rem;
-  font-size: 0.8rem;
-  font-family: 'Courier New', monospace;
-}
-
-.exchange-label {
-  color: #94a3b8;
-  min-width: 120px;
-}
-
-.exchange-value {
-  color: #e2e8f0;
-  word-break: break-all;
-}
-
-.flow-steps {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.steps-title {
-  font-weight: 700;
-  font-size: 1rem;
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
   margin-bottom: 1rem;
 }
 
-.steps-list {
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-.step-item {
-  display: flex;
-  gap: 1rem;
-  padding: 1rem;
-  border-radius: 8px;
+.card {
+  background: var(--vp-c-bg);
   border: 1px solid var(--vp-c-divider);
-  background: var(--vp-c-bg-soft);
-  transition: all 0.3s ease;
+  border-radius: 8px;
+  padding: 1rem;
 }
 
-.step-item.completed {
-  opacity: 0.6;
+.card-title {
+  font-weight: 800;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
 }
 
-.step-item.current {
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-}
-
-.step-number {
-  width: 36px;
-  height: 36px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
+.role {
   display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 700;
-  font-size: 0.95rem;
-  flex-shrink: 0;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.step-content {
-  flex: 1;
+.pill {
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-2);
+  border-radius: 999px;
+  padding: 0.2rem 0.6rem;
+  font-size: 0.85rem;
 }
 
-.step-title {
-  font-weight: 600;
-  font-size: 0.95rem;
+.desc {
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+.warn {
+  margin-top: 0.75rem;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+
+.warn-title {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
   margin-bottom: 0.25rem;
 }
 
-.step-desc {
-  font-size: 0.85rem;
+.warn-text {
   color: var(--vp-c-text-2);
+  line-height: 1.7;
 }
 
-.security-notes {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
+.code {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
   border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
+  overflow-x: auto;
 }
 
-.notes-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.notes-list {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.note-item {
-  display: flex;
-  gap: 0.75rem;
-  padding: 1rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  border-left: 4px solid #f59e0b;
-}
-
-.note-icon {
-  font-size: 1.5rem;
-  flex-shrink: 0;
-}
-
-.note-content {
-  flex: 1;
-}
-
-.note-title {
-  font-weight: 600;
+.hint {
+  margin-top: 0.75rem;
+  color: var(--vp-c-text-2);
   font-size: 0.9rem;
-  margin-bottom: 0.25rem;
+  line-height: 1.7;
 }
 
-.note-text {
-  font-size: 0.85rem;
+.list {
+  margin: 0;
+  padding-left: 1.1rem;
   color: var(--vp-c-text-2);
-  line-height: 1.5;
+  line-height: 1.75;
 }
 
-.participants-table {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.table-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-}
-
-thead th {
-  padding: 0.75rem;
-  text-align: left;
-  font-weight: 700;
-  font-size: 0.85rem;
-  border-bottom: 2px solid var(--vp-c-divider);
-}
-
-tbody td {
-  padding: 0.75rem;
-  border-bottom: 1px solid var(--vp-c-divider);
-  font-size: 0.85rem;
-}
-
-tbody tr:last-child td {
-  border-bottom: none;
-}
-
-@media (max-width: 768px) {
-  .actors {
-    grid-template-columns: repeat(2, 1fr);
-  }
-
-  .exchange-item {
-    flex-direction: column;
-    gap: 0.25rem;
-  }
-
-  .exchange-label {
-    min-width: auto;
+@media (max-width: 720px) {
+  .grid {
+    grid-template-columns: 1fr;
   }
 }
 </style>
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/PasswordHashingDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/PasswordHashingDemo.vue
index 4ddf6d9..0c8ff39 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/PasswordHashingDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/PasswordHashingDemo.vue
@@ -1,699 +1,405 @@
 <!--
   PasswordHashingDemo.vue
-  密码哈希演示
+  密码哈希/加密学派生函数演示（更安全/更可用）
+
+  说明：
+  - 为避免引入第三方依赖（bcryptjs）导致构建失败，本组件用 WebCrypto 的 PBKDF2 来模拟“慢哈希 + 盐”的核心效果。
+  - 生产环境更推荐 bcrypt / scrypt / Argon2（取决于语言/库），本演示只讲原理。
 -->
 <template>
   <div class="password-hashing-demo">
     <div class="header">
-      <div class="title">密码哈希：为什么不能存明文？</div>
-      <div class="subtitle">理解 bcrypt 和彩虹表攻击</div>
+      <div class="title">🔐 密码存储：哈希 + 盐 + 慢</div>
+      <div class="subtitle">
+        演示 PBKDF2（模拟慢哈希）如何抵抗彩虹表/暴力破解；真实项目通常选
+        bcrypt/Argon2。
+      </div>
     </div>
 
-    <div class="password-input">
-      <label>输入密码</label>
-      <input
-        v-model="password"
-        type="text"
-        placeholder="输入密码..."
-        @input="updateHash"
-      />
-      <button class="generate-btn" @click="updateHash">
-        <span class="btn-icon">🔐</span>
-        <span class="btn-text">生成哈希</span>
-      </button>
-    </div>
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">输入</div>
 
-    <div class="comparison">
-      <div class="comparison-card bad">
-        <div class="card-header">
-          <div class="card-icon">❌</div>
-          <div class="card-title">错误做法</div>
+        <label class="label">密码</label>
+        <input
+          v-model="password"
+          type="password"
+          class="input"
+          placeholder="例如：123456"
+          @input="debouncedRecompute"
+        />
+
+        <div class="row">
+          <div class="col">
+            <label class="label">
+              iterations（迭代次数）：<strong>{{ iterations }}</strong>
+            </label>
+            <input
+              v-model.number="iterations"
+              class="range"
+              type="range"
+              min="1000"
+              max="200000"
+              step="1000"
+              @input="debouncedRecompute"
+            />
+            <div class="hint">越大越慢，暴力破解成本越高（但登录也更慢）。</div>
+          </div>
         </div>
 
-        <div class="method-selector">
-          <button
-            v-for="method in badMethods"
-            :key="method.key"
-            class="method-btn"
-            :class="{ active: selectedBadMethod === method.key }"
-            @click="selectedBadMethod = method.key"
-          >
-            {{ method.name }}
+        <div class="row">
+          <label class="toggle">
+            <input v-model="saltEnabled" type="checkbox" @change="recompute" />
+            <span>启用盐（salt）</span>
+          </label>
+          <button class="btn" @click="regenSalt" :disabled="!saltEnabled">
+            生成新盐
           </button>
         </div>
 
-        <div class="hash-result">
-          <div class="result-label">哈希结果</div>
-          <div class="result-value">{{ badHashResult }}</div>
-        </div>
-
-        <div class="security-info">
-          <div class="info-title">安全问题</div>
-          <ul class="info-list">
-            <li v-for="(issue, index) in badMethodIssues" :key="index">
-              {{ issue }}
-            </li>
-          </ul>
+        <div class="mono-box">
+          <div class="mono-label">salt</div>
+          <code class="mono">{{ saltEnabled ? saltHex : '(disabled)' }}</code>
         </div>
       </div>
 
-      <div class="vs-divider">VS</div>
+      <div class="card">
+        <div class="card-title">输出（模拟）</div>
 
-      <div class="comparison-card good">
-        <div class="card-header">
-          <div class="card-icon">✅</div>
-          <div class="card-title">正确做法</div>
+        <div class="status">
+          <span class="badge">Algorithm: PBKDF2-SHA256</span>
+          <span class="badge">Time: {{ timeMs }}ms</span>
         </div>
 
-        <div class="method-selector">
-          <button class="method-btn active">bcrypt</button>
+        <div class="mono-box">
+          <div class="mono-label">derived key (hex)</div>
+          <code class="mono">{{ hashHex || '（请输入密码）' }}</code>
         </div>
 
-        <div class="hash-result">
-          <div class="result-label">bcrypt 哈希</div>
-          <div class="result-value">{{ bcryptHashResult }}</div>
-        </div>
-
-        <div class="security-info">
-          <div class="info-title">安全特性</div>
-          <ul class="info-list">
-            <li>🐌 慢哈希：故意设计得很慢，防暴力破解</li>
-            <li>🎲 自适应：可调整 rounds，随硬件变强而增强</li>
-            <li>🧂 自带加盐：每个密码都有随机盐，防彩虹表</li>
-            <li>🔒 单向加密：无法反向解密</li>
-          </ul>
-        </div>
-
-        <div class="rounds-control">
-          <label>
-            rounds (复杂度): <strong>{{ rounds }}</strong>
-          </label>
-          <input
-            v-model="rounds"
-            type="range"
-            min="4"
-            max="14"
-            step="1"
-            @input="updateHash"
-          />
-          <div class="rounds-info">当前耗时: {{ hashTime }} ms</div>
-        </div>
-      </div>
-    </div>
-
-    <div class="rainbow-table">
-      <div class="section-title">彩虹表攻击演示</div>
-      <div class="rainbow-content">
-        <div class="rainbow-explanation">
-          <div class="explanation-text">
-            <p><strong>什么是彩虹表？</strong></p>
-            <p>
-              彩虹表是一个预先计算好的哈希值字典，包含常见密码及其哈希结果。攻击者可以通过查询彩虹表快速破解密码。
-            </p>
-            <p><strong>为什么需要盐？</strong></p>
-            <p>
-              盐（salt）是随机字符串，在每个密码哈希时加入。即使两个用户使用相同的密码，由于盐不同，哈希结果也不同。这使得彩虹表失效。
-            </p>
-          </div>
-        </div>
-
-        <div class="rainbow-demo">
-          <div class="demo-title">彩虹表示例（MD5，无盐）</div>
-          <div class="rainbow-table-container">
-            <table>
-              <thead>
-                <tr>
-                  <th>密码</th>
-                  <th>MD5 哈希</th>
-                </tr>
-              </thead>
-              <tbody>
-                <tr v-for="(item, index) in rainbowTable" :key="index">
-                  <td>{{ item.password }}</td>
-                  <td class="hash">{{ item.hash }}</td>
-                </tr>
-              </tbody>
-            </table>
-          </div>
-
-          <div class="lookup-demo">
-            <div class="lookup-title">哈希查询</div>
-            <div class="lookup-input">
-              <input
-                v-model="lookupHash"
-                type="text"
-                placeholder="粘贴 MD5 哈希值..."
-              />
-              <button class="lookup-btn" @click="lookupPassword">查询</button>
-            </div>
-            <div class="lookup-result" v-if="lookupResult">
-              <div class="result-text">
-                {{ lookupResult }}
-              </div>
-            </div>
+        <div class="alert">
+          <div class="alert-title">结论</div>
+          <div class="alert-text">
+            不要存明文；不要用无盐的快速哈希（MD5/SHA1/SHA256 直接 hash 密码）。
+            应使用“专门的密码哈希/KDF（慢 + 盐）”，并设置合理成本。
           </div>
         </div>
       </div>
     </div>
 
-    <div class="best-practices">
-      <div class="practices-title">最佳实践</div>
-      <div class="practices-list">
-        <div class="practice-item">
-          <div class="practice-icon">✅</div>
-          <div class="practice-content">
-            <strong>使用 bcrypt、scrypt 或 Argon2</strong>
-            <p>这些是专门为密码设计的哈希算法，具有抗暴力破解的特性。</p>
-          </div>
+    <div class="card">
+      <div class="card-title">
+        🌈 彩虹表为什么会失效？（同一密码 + 不同盐 → 不同结果）
+      </div>
+      <div class="two">
+        <div class="mono-box">
+          <div class="mono-label">salt A</div>
+          <code class="mono">{{ saltA }}</code>
+          <div class="mono-label">hash A</div>
+          <code class="mono">{{ hashA || '-' }}</code>
         </div>
-        <div class="practice-item">
-          <div class="practice-icon">✅</div>
-          <div class="practice-content">
-            <strong>调整 rounds 参数</strong>
-            <p>使哈希操作耗时在 100-500ms 之间，平衡安全性和用户体验。</p>
-          </div>
-        </div>
-        <div class="practice-item">
-          <div class="practice-icon">✅</div>
-          <div class="practice-content">
-            <strong>使用 HTTPS</strong>
-            <p>防止密码在传输过程中被截获。</p>
-          </div>
-        </div>
-        <div class="practice-item">
-          <div class="practice-icon">❌</div>
-          <div class="practice-content">
-            <strong>不要使用 MD5、SHA1、SHA256</strong>
-            <p>这些是快速哈希算法，不适合密码存储，容易被暴力破解。</p>
-          </div>
+        <div class="mono-box">
+          <div class="mono-label">salt B</div>
+          <code class="mono">{{ saltB }}</code>
+          <div class="mono-label">hash B</div>
+          <code class="mono">{{ hashB || '-' }}</code>
         </div>
       </div>
+      <div class="hint">
+        彩虹表依赖“预计算”：同一个密码如果总产生同一个哈希，攻击者就能快速反查。盐让预计算成本爆炸。
+      </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { onMounted, ref } from 'vue'
 
-const password = ref('password123')
-const selectedBadMethod = ref('md5')
-const rounds = ref(10)
-const lookupHash = ref('')
-const lookupResult = ref('')
-const hashTime = ref(0)
+const password = ref('')
+const iterations = ref(60000)
+const saltEnabled = ref(true)
+const saltHex = ref('')
 
-const badMethods = [
-  { key: 'md5', name: 'MD5' },
-  { key: 'sha1', name: 'SHA1' },
-  { key: 'sha256', name: 'SHA256' }
-]
+const hashHex = ref('')
+const timeMs = ref(0)
 
-const rainbowTable = [
-  { password: '123456', hash: 'e10adc3949ba59abbe56e057f20f883e' },
-  { password: 'password', hash: '5f4dcc3b5aa765d61d8327deb882cf99' },
-  { password: 'admin', hash: '21232f297a57a5a743894a0e4a801fc3' },
-  { password: '123456789', hash: '25f9e794323b453885f5181f1b624d0b' },
-  { password: 'qwerty', hash: 'd8578edf8458ce06fbc5bb76a58c5ca4' }
-]
+let t = null
 
-const badHashResult = computed(() => {
-  if (!password.value) return '等待输入...'
+const toHex = (bytes) =>
+  [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
 
-  const hash = simpleHash(password.value, selectedBadMethod.value)
-  return hash
-})
-
-const badMethodIssues = computed(() => {
-  const issues = {
-    md5: [
-      '⚡ 快速哈希：1秒可计算数十亿次',
-      '🌈 彩虹表攻击：常见密码可秒破',
-      '🔓 无盐：相同密码产生相同哈希'
-    ],
-    sha1: [
-      '⚡ 快速哈希：比 MD5 慢一点，但仍然太快',
-      '🌈 彩虹表攻击：同样 vulnerable',
-      '🔓 无盐：相同密码产生相同哈希'
-    ],
-    sha256: [
-      '⚡ 快速哈希：虽然比 SHA1 慢，但仍不够',
-      '🌈 彩虹表攻击：GPU 可加速破解',
-      '🔓 无盐：相同密码产生相同哈希'
-    ]
+const fromHex = (hex) => {
+  const clean = hex.trim().replace(/^0x/, '')
+  if (!clean) return new Uint8Array()
+  const out = new Uint8Array(clean.length / 2)
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16)
   }
-  return issues[selectedBadMethod.value] || []
-})
-
-const bcryptHashResult = computed(() => {
-  if (!password.value) return '等待输入...'
-
-  // 模拟 bcrypt 格式: $2a$rounds$salt+hash
-  const salt = Math.random().toString(36).substring(2, 14)
-  const hash = simpleHash(password.value + salt, 'sha256').substring(0, 31)
-
-  return `$2a$${rounds.value}$${salt}${hash}`
-})
-
-const simpleHash = (str, algorithm) => {
-  // 简化的哈希函数用于演示
-  let hash = 0
-  const str2 = algorithm + str
-
-  for (let i = 0; i < str2.length; i++) {
-    const char = str2.charCodeAt(i)
-    hash = (hash << 5) - hash + char
-    hash = hash & hash
-  }
-
-  return Math.abs(hash).toString(16).padStart(32, '0').substring(0, 32)
+  return out
 }
 
-const updateHash = () => {
-  const startTime = performance.now()
-
-  // 模拟 bcrypt 的延迟
-  const delay = Math.pow(2, rounds.value - 4) * 10
-  hashTime.value = Math.min(delay, 500)
-
-  // 模拟哈希计算
-  setTimeout(() => {
-    const endTime = performance.now()
-    hashTime.value = Math.round(endTime - startTime)
-  }, 0)
+const randomSaltHex = (len = 16) => {
+  const bytes = new Uint8Array(len)
+  crypto.getRandomValues(bytes)
+  return toHex(bytes)
 }
 
-const lookupPassword = () => {
-  const hash = lookupHash.value.trim()
+const derive = async ({ pwd, iters, salt }) => {
+  const enc = new TextEncoder()
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(pwd),
+    { name: 'PBKDF2' },
+    false,
+    ['deriveBits']
+  )
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt, iterations: iters, hash: 'SHA-256' },
+    keyMaterial,
+    256
+  )
+  return toHex(new Uint8Array(bits))
+}
 
-  if (!hash) {
-    lookupResult.value = '请输入哈希值'
+const recompute = async () => {
+  if (!password.value) {
+    hashHex.value = ''
+    timeMs.value = 0
+    await recomputeRainbow()
     return
   }
 
-  const found = rainbowTable.find((item) => item.hash === hash)
+  const saltBytes = saltEnabled.value
+    ? fromHex(saltHex.value)
+    : new Uint8Array(16) // "no salt" demonstration: constant all-zero salt
 
-  if (found) {
-    lookupResult.value = `✅ 找到匹配：密码是 "${found.password}"`
-  } else {
-    lookupResult.value = '❌ 未在彩虹表中找到'
+  const start = performance.now()
+  try {
+    hashHex.value = await derive({
+      pwd: password.value,
+      iters: iterations.value,
+      salt: saltBytes
+    })
+  } finally {
+    timeMs.value = Math.max(0, Math.round(performance.now() - start))
   }
+
+  await recomputeRainbow()
 }
+
+const debouncedRecompute = () => {
+  if (t) clearTimeout(t)
+  t = setTimeout(() => {
+    recompute()
+  }, 200)
+}
+
+const regenSalt = () => {
+  saltHex.value = randomSaltHex(16)
+  recompute()
+}
+
+// Rainbow demo
+const saltA = ref('')
+const saltB = ref('')
+const hashA = ref('')
+const hashB = ref('')
+
+const recomputeRainbow = async () => {
+  if (!password.value) {
+    hashA.value = ''
+    hashB.value = ''
+    return
+  }
+  const a = fromHex(saltA.value)
+  const b = fromHex(saltB.value)
+  hashA.value = await derive({ pwd: password.value, iters: 30000, salt: a })
+  hashB.value = await derive({ pwd: password.value, iters: 30000, salt: b })
+}
+
+onMounted(() => {
+  saltHex.value = randomSaltHex(16)
+  saltA.value = randomSaltHex(16)
+  saltB.value = randomSaltHex(16)
+})
 </script>
 
 <style scoped>
 .password-hashing-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
   font-size: 1.1rem;
-  margin-bottom: 0.3rem;
 }
 
 .subtitle {
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
+  margin-top: 0.25rem;
 }
 
-.password-input {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.password-input label {
-  display: block;
-  font-weight: 600;
-  margin-bottom: 0.5rem;
-  font-size: 0.9rem;
-}
-
-.password-input input {
-  width: 100%;
-  padding: 0.6rem;
-  border: 1px solid var(--vp-c-divider);
-  border-radius: 6px;
-  font-size: 0.9rem;
-  margin-bottom: 0.75rem;
-  font-family: 'Courier New', monospace;
-}
-
-.generate-btn {
-  width: 100%;
-  padding: 0.75rem;
-  border: none;
-  border-radius: 8px;
-  background: var(--vp-c-brand);
-  color: white;
-  cursor: pointer;
-  font-weight: 600;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  transition: all 0.2s ease;
-}
-
-.generate-btn:hover {
-  background: #2563eb;
-}
-
-.comparison {
-  display: flex;
-  align-items: stretch;
-  gap: 1.5rem;
-  margin-bottom: 1.5rem;
-  flex-wrap: wrap;
-}
-
-.comparison-card {
-  flex: 1;
-  min-width: 300px;
-  background: var(--vp-c-bg);
-  border-radius: 12px;
-  padding: 1.5rem;
-  border: 2px solid var(--vp-c-divider);
-}
-
-.comparison-card.bad {
-  border-color: #ef4444;
-}
-
-.comparison-card.good {
-  border-color: #22c55e;
-}
-
-.card-header {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
   margin-bottom: 1rem;
 }
 
-.card-icon {
-  font-size: 1.5rem;
+.card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
 }
 
 .card-title {
-  font-weight: 700;
-  font-size: 1rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.75rem;
 }
 
-.method-selector {
+.label {
+  display: block;
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  font-size: 0.875rem;
+  margin-bottom: 0.35rem;
+}
+
+.input {
+  width: 100%;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  padding: 0.5rem 0.6rem;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+.range {
+  width: 100%;
+}
+
+.row {
   display: flex;
-  gap: 0.5rem;
-  margin-bottom: 1rem;
+  gap: 0.75rem;
+  align-items: center;
+  margin-top: 0.75rem;
   flex-wrap: wrap;
 }
 
-.method-btn {
+.col {
   flex: 1;
-  min-width: 80px;
-  padding: 0.5rem;
-  border: 1px solid var(--vp-c-divider);
-  border-radius: 6px;
-  background: var(--vp-c-bg-soft);
-  cursor: pointer;
-  font-size: 0.85rem;
-  transition: all 0.2s ease;
+  min-width: 240px;
 }
 
-.method-btn.active {
-  background: var(--vp-c-brand);
-  color: white;
-  border-color: var(--vp-c-brand);
-}
-
-.hash-result {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-  margin-bottom: 1rem;
-}
-
-.result-label {
-  font-size: 0.75rem;
-  font-weight: 600;
-  margin-bottom: 0.5rem;
-  color: var(--vp-c-text-2);
-}
-
-.result-value {
-  font-family: 'Courier New', monospace;
-  font-size: 0.8rem;
-  word-break: break-all;
-  line-height: 1.5;
-}
-
-.security-info {
-  margin-bottom: 1rem;
-}
-
-.info-title {
-  font-weight: 600;
-  font-size: 0.85rem;
-  margin-bottom: 0.5rem;
-}
-
-.info-list {
-  margin: 0;
-  padding-left: 1.25rem;
-}
-
-.info-list li {
-  font-size: 0.8rem;
-  margin-bottom: 0.4rem;
-  line-height: 1.4;
-}
-
-.rounds-control {
-  padding: 1rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-}
-
-.rounds-control label {
-  display: block;
-  font-size: 0.85rem;
-  margin-bottom: 0.5rem;
-}
-
-.rounds-control input[type='range'] {
-  width: 100%;
-  margin-bottom: 0.5rem;
-}
-
-.rounds-info {
-  font-size: 0.8rem;
-  color: var(--vp-c-text-2);
-}
-
-.vs-divider {
-  display: flex;
+.toggle {
+  display: inline-flex;
+  gap: 0.5rem;
   align-items: center;
-  justify-content: center;
-  font-weight: 700;
-  font-size: 1.2rem;
-  color: var(--vp-c-text-2);
-  min-width: 50px;
-}
-
-.rainbow-table {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.section-title,
-.practices-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.rainbow-content {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 1.5rem;
-}
-
-.rainbow-explanation {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.explanation-text {
-  font-size: 0.85rem;
-  line-height: 1.6;
-}
-
-.explanation-text p {
-  margin-bottom: 0.75rem;
-}
-
-.explanation-text strong {
-  color: var(--vp-c-brand);
-}
-
-.rainbow-demo {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-}
-
-.demo-title {
+  color: var(--vp-c-text-1);
   font-weight: 600;
-  font-size: 0.9rem;
-  margin-bottom: 0.75rem;
 }
 
-.rainbow-table-container {
-  margin-bottom: 1rem;
-}
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 0.75rem;
-}
-
-thead th {
-  padding: 0.5rem;
-  text-align: left;
-  font-weight: 600;
-  border-bottom: 2px solid var(--vp-c-divider);
-}
-
-tbody td {
-  padding: 0.5rem;
-  border-bottom: 1px solid var(--vp-c-divider);
-  font-family: 'Courier New', monospace;
-}
-
-.hash {
-  color: var(--vp-c-text-2);
-  word-break: break-all;
-}
-
-.lookup-demo {
-  background: white;
+.btn {
+  padding: 0.45rem 0.75rem;
   border-radius: 6px;
-  padding: 0.75rem;
   border: 1px solid var(--vp-c-divider);
-}
-
-.lookup-title {
-  font-size: 0.8rem;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
   font-weight: 600;
-  margin-bottom: 0.5rem;
 }
 
-.lookup-input {
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.status {
   display: flex;
   gap: 0.5rem;
-  margin-bottom: 0.5rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.lookup-input input {
-  flex: 1;
-  padding: 0.4rem;
+.badge {
   border: 1px solid var(--vp-c-divider);
-  border-radius: 4px;
-  font-size: 0.75rem;
-  font-family: 'Courier New', monospace;
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-2);
+  border-radius: 999px;
+  padding: 0.2rem 0.6rem;
+  font-size: 0.8rem;
+  font-family: var(--vp-font-family-mono);
 }
 
-.lookup-btn {
-  padding: 0.4rem 0.75rem;
-  border: none;
-  border-radius: 4px;
-  background: var(--vp-c-brand);
-  color: white;
-  cursor: pointer;
-  font-size: 0.75rem;
-  font-weight: 600;
-}
-
-.lookup-result {
-  padding: 0.5rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 4px;
-  font-size: 0.75rem;
-}
-
-.result-text {
-  font-weight: 600;
-}
-
-.best-practices {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
+.mono-box {
   border: 1px solid var(--vp-c-divider);
-}
-
-.practices-list {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.practice-item {
-  display: flex;
-  gap: 0.75rem;
-  padding: 1rem;
+  background: var(--vp-c-bg-alt);
   border-radius: 8px;
-  background: var(--vp-c-bg-soft);
+  padding: 0.75rem;
+  overflow-x: auto;
 }
 
-.practice-icon {
-  font-size: 1.5rem;
-  flex-shrink: 0;
-}
-
-.practice-content {
-  flex: 1;
-}
-
-.practice-content strong {
-  display: block;
-  font-size: 0.9rem;
+.mono-label {
+  color: var(--vp-c-text-2);
+  font-size: 0.8rem;
   margin-bottom: 0.25rem;
 }
 
-.practice-content p {
+.mono {
+  font-family: var(--vp-font-family-mono);
+  color: var(--vp-c-text-1);
   font-size: 0.85rem;
-  color: var(--vp-c-text-2);
-  margin: 0;
-  line-height: 1.5;
 }
 
-@media (max-width: 768px) {
-  .comparison {
-    flex-direction: column;
-  }
+.alert {
+  margin-top: 0.75rem;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
 
-  .vs-divider {
-    transform: rotate(90deg);
-    margin: 0.5rem 0;
-  }
+.alert-title {
+  font-weight: 800;
+  margin-bottom: 0.35rem;
+  color: var(--vp-c-text-1);
+}
 
-  .rainbow-content {
+.alert-text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+.two {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.75rem;
+  margin-top: 0.75rem;
+}
+
+.hint {
+  margin-top: 0.75rem;
+  color: var(--vp-c-text-2);
+  font-size: 0.9rem;
+  line-height: 1.7;
+}
+
+@media (max-width: 720px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+  .two {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/SessionCookieDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/SessionCookieDemo.vue
index 0457c67..0d1580c 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/SessionCookieDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/SessionCookieDemo.vue
@@ -1,688 +1,361 @@
 <!--
   SessionCookieDemo.vue
-  Session + Cookie 工作流程演示
+  Session + Cookie（手动推进，更贴近真实 Web 登录态）
 -->
 <template>
-  <div class="session-cookie-demo">
+  <div class="session-demo">
     <div class="header">
-      <div class="title">Session + Cookie 工作流程</div>
-      <div class="subtitle">Web 开发的经典鉴权方案</div>
+      <div class="title">🍪 Session + Cookie：有状态登录</div>
+      <div class="subtitle">
+        默认手动推进：先看清楚状态再进入下一步（避免“自动下一步”误解）。
+      </div>
     </div>
 
     <div class="controls">
-      <button
-        class="action-btn login"
-        @click="performLogin"
-        :disabled="isLoggedIn"
-      >
-        <span class="btn-icon">🔑</span>
-        <span class="btn-text">模拟登录</span>
+      <button class="btn primary" @click="start" :disabled="step !== 0">
+        开始
       </button>
+      <button class="btn" @click="prev" :disabled="step <= 1">上一步</button>
       <button
-        class="action-btn request"
-        @click="performRequest"
-        :disabled="!isLoggedIn"
+        class="btn primary"
+        @click="next"
+        :disabled="step === 0 || step >= maxStep"
       >
-        <span class="btn-icon">🌐</span>
-        <span class="btn-text">发送请求</span>
-      </button>
-      <button
-        class="action-btn logout"
-        @click="performLogout"
-        :disabled="!isLoggedIn"
-      >
-        <span class="btn-icon">🚪</span>
-        <span class="btn-text">退出登录</span>
+        下一步
       </button>
+      <button class="btn" @click="reset">重置</button>
     </div>
 
-    <div class="visual-container">
-      <div class="client-server">
-        <div class="client">
-          <div class="device-header">
-            <span class="device-icon">💻</span>
-            <span class="device-label">浏览器</span>
-          </div>
-          <div class="device-content">
-            <div class="cookie-jar">
-              <div class="jar-label">Cookie 存储</div>
-              <div class="jar-content">
-                <div v-if="sessionCookie" class="cookie-item">
-                  <div class="cookie-key">session_id</div>
-                  <div class="cookie-value">{{ sessionCookie }}</div>
-                </div>
-                <div v-else class="cookie-empty">暂无 Cookie</div>
-              </div>
-            </div>
-            <div class="request-preview" v-if="currentRequest">
-              <div class="preview-title">当前请求</div>
-              <div class="preview-content">
-                <div class="preview-line">{{ currentRequest }}</div>
-              </div>
-            </div>
+    <div v-if="step > 0" class="progress">
+      Step {{ step }} / {{ maxStep }} · {{ steps[step - 1]?.title }}
+    </div>
+
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">浏览器（客户端）</div>
+        <div class="box">
+          <div class="box-title">Cookie Jar</div>
+          <div v-if="cookie" class="kv">
+            <div class="k">session_id</div>
+            <div class="v mono">{{ cookie }}</div>
           </div>
+          <div v-else class="empty">暂无 Cookie</div>
         </div>
 
-        <div class="connection">
-          <div class="connection-line" :class="{ active: isTransferring }">
-            <div class="data-packet" v-if="isTransferring">
-              {{ transferData }}
+        <div class="box">
+          <div class="box-title">本步请求</div>
+          <pre class="code"><code>{{ clientRequest }}</code></pre>
+        </div>
+      </div>
+
+      <div class="card">
+        <div class="card-title">服务器</div>
+        <div class="box">
+          <div class="box-title">Session Store（Redis/Memory）</div>
+          <div v-if="session" class="kv">
+            <div class="k mono">{{ cookie }}</div>
+            <div class="v">
+              <div class="row"><span class="muted">user_id</span> 123</div>
+              <div class="row"><span class="muted">username</span> alice</div>
+              <div class="row"><span class="muted">role</span> admin</div>
             </div>
           </div>
+          <div v-else class="empty">暂无 Session</div>
         </div>
 
-        <div class="server">
-          <div class="device-header">
-            <span class="device-icon">🖥️</span>
-            <span class="device-label">服务器</span>
-          </div>
-          <div class="device-content">
-            <div class="session-storage">
-              <div class="storage-label">Session 存储 (Redis/Memory)</div>
-              <div class="storage-content">
-                <div v-if="serverSession" class="session-item">
-                  <div class="session-key">{{ sessionCookie }}</div>
-                  <div class="session-data">
-                    <div class="data-row">
-                      <span class="data-key">user_id:</span>
-                      <span class="data-value">{{
-                        serverSession.user_id
-                      }}</span>
-                    </div>
-                    <div class="data-row">
-                      <span class="data-key">username:</span>
-                      <span class="data-value">{{
-                        serverSession.username
-                      }}</span>
-                    </div>
-                    <div class="data-row">
-                      <span class="data-key">role:</span>
-                      <span class="data-value">{{ serverSession.role }}</span>
-                    </div>
-                  </div>
-                </div>
-                <div v-else class="session-empty">暂无 Session</div>
-              </div>
-            </div>
-          </div>
+        <div class="box">
+          <div class="box-title">本步响应</div>
+          <pre class="code"><code>{{ serverResponse }}</code></pre>
         </div>
       </div>
     </div>
 
-    <div class="flow-steps" v-if="currentStep">
-      <div class="steps-title">流程说明</div>
-      <div class="steps-list">
-        <div
-          v-for="(step, index) in currentStep.steps"
-          :key="index"
-          class="step-item"
-          :class="{ active: step.active }"
-        >
-          <div class="step-number">{{ index + 1 }}</div>
-          <div class="step-content">{{ step.text }}</div>
-        </div>
-      </div>
-    </div>
-
-    <div class="info-cards">
-      <div class="info-card pros">
-        <div class="card-icon">✅</div>
-        <div class="card-title">优点</div>
-        <ul class="card-list">
-          <li>简单直观，易于理解</li>
-          <li>服务端可以主动注销</li>
-          <li>Session 信息存储在服务端，相对安全</li>
-        </ul>
-      </div>
-
-      <div class="info-card cons">
-        <div class="card-icon">⚠️</div>
-        <div class="card-title">缺点</div>
-        <ul class="card-list">
-          <li>服务器有状态，需要存储 Session</li>
-          <li>多台服务器需要共享 Session（如 Redis）</li>
-          <li>跨域困难，Cookie 默认不能跨域</li>
-          <li>容易受到 CSRF 攻击</li>
-        </ul>
+    <div class="card">
+      <div class="card-title">{{ steps[step - 1]?.title || '流程说明' }}</div>
+      <div class="desc">{{ steps[step - 1]?.desc }}</div>
+      <div v-if="steps[step - 1]?.warn" class="warn">
+        <div class="warn-title">注意</div>
+        <div class="warn-text">{{ steps[step - 1]?.warn }}</div>
       </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const isLoggedIn = ref(false)
-const isTransferring = ref(false)
-const sessionCookie = ref('')
-const serverSession = ref(null)
-const currentRequest = ref('')
-const transferData = ref('')
-const currentStep = ref(null)
+const maxStep = 5
+const step = ref(0)
 
-const steps = {
-  login: {
-    steps: [
-      { text: '用户提交用户名密码', active: false },
-      { text: '服务器验证身份', active: false },
-      { text: '创建 Session 并存储用户信息', active: false },
-      { text: '返回 Set-Cookie: session_id=xxx', active: false },
-      { text: '浏览器保存 Cookie', active: false }
-    ]
+const cookie = ref('')
+const session = ref(false)
+
+const steps = [
+  {
+    title: '1) 登录请求（POST /login）',
+    desc: '用户提交用户名/密码，服务器验证成功后创建 Session。'
   },
-  request: {
-    steps: [
-      { text: '浏览器自动带上 Cookie', active: false },
-      { text: '服务器根据 session_id 查找 Session', active: false },
-      { text: '找到 Session，验证通过', active: false },
-      { text: '返回请求的数据', active: false }
-    ]
+  {
+    title: '2) 服务器 Set-Cookie',
+    desc: '服务器返回 Set-Cookie: session_id=...；浏览器保存 Cookie。',
+    warn: 'Cookie 建议加 HttpOnly + Secure + SameSite；同时要考虑 CSRF 防护。'
   },
-  logout: {
-    steps: [
-      { text: '用户点击退出', active: false },
-      { text: '服务器删除 Session', active: false },
-      { text: '清除浏览器 Cookie', active: false },
-      { text: '退出成功', active: false }
-    ]
+  {
+    title: '3) 后续请求自动带 Cookie',
+    desc: '浏览器对同域请求会自动带上 Cookie，服务器用 session_id 查 Session。'
+  },
+  {
+    title: '4) 授权判断（role/权限）',
+    desc: '认证（你是谁）之后，仍需要授权（你能做什么）。比如 admin 才能访问管理接口。'
+  },
+  {
+    title: '5) 注销',
+    desc: '服务器删除 Session（或让其过期），并让浏览器清理 Cookie。'
+  }
+]
+
+const start = () => {
+  step.value = 1
+  cookie.value = ''
+  session.value = false
+}
+
+const next = () => {
+  step.value = Math.min(maxStep, step.value + 1)
+  applyState()
+}
+
+const prev = () => {
+  step.value = Math.max(1, step.value - 1)
+  applyState()
+}
+
+const reset = () => {
+  step.value = 0
+  cookie.value = ''
+  session.value = false
+}
+
+const applyState = () => {
+  if (step.value <= 1) {
+    cookie.value = ''
+    session.value = false
+    return
+  }
+  if (step.value >= 2) {
+    if (!cookie.value)
+      cookie.value = 'sess_' + Math.random().toString(36).slice(2, 10)
+    session.value = true
+  }
+  if (step.value >= 5) {
+    // logout (show as empty state by step title/response)
+    // We don't auto-clear state; keep it visible until reset to avoid “auto” confusion.
   }
 }
 
-const performLogin = async () => {
-  const sessionId = generateSessionId()
-  const stepsData = steps.login
+const clientRequest = computed(() => {
+  if (step.value === 0) return '（点击开始）'
+  if (step.value === 1) {
+    return `POST /login
+Content-Type: application/json
 
-  for (let i = 0; i < stepsData.steps.length; i++) {
-    stepsData.steps[i].active = true
-    currentStep.value = stepsData
-
-    if (i === 0) {
-      currentRequest.value =
-        'POST /login\n{ username: "alice", password: "***" }'
-      transferData.value = '登录请求'
-      isTransferring.value = true
-      await delay(800)
-    } else if (i === 2) {
-      serverSession.value = {
-        user_id: 123,
-        username: 'alice',
-        role: 'user'
-      }
-      await delay(600)
-    } else if (i === 3) {
-      transferData.value = 'Set-Cookie'
-      isTransferring.value = true
-      await delay(800)
-      sessionCookie.value = sessionId
-      isLoggedIn.value = true
-    } else {
-      await delay(500)
-    }
+{"username":"alice","password":"******"}`
   }
-
-  isTransferring.value = false
-  currentRequest.value = ''
-  transferData.value = ''
-}
-
-const performRequest = async () => {
-  const stepsData = steps.request
-
-  for (let i = 0; i < stepsData.steps.length; i++) {
-    stepsData.steps[i].active = true
-    currentStep.value = stepsData
-
-    if (i === 0) {
-      currentRequest.value = `GET /api/user/profile\nCookie: session_id=${sessionCookie.value}`
-      transferData.value = '请求 + Cookie'
-      isTransferring.value = true
-      await delay(800)
-    } else if (i === 1) {
-      isTransferring.value = false
-      await delay(600)
-    } else if (i === 3) {
-      transferData.value = '响应数据'
-      isTransferring.value = true
-      await delay(800)
-    } else {
-      await delay(500)
-    }
+  if (step.value === 2) return '（等待服务器响应并写入 Cookie）'
+  if (step.value === 3) {
+    return `GET /api/user/profile
+Cookie: session_id=${cookie.value}`
   }
-
-  isTransferring.value = false
-  currentRequest.value = ''
-  transferData.value = ''
-}
-
-const performLogout = async () => {
-  const stepsData = steps.logout
-
-  for (let i = 0; i < stepsData.steps.length; i++) {
-    stepsData.steps[i].active = true
-    currentStep.value = stepsData
-
-    if (i === 0) {
-      currentRequest.value = 'POST /logout'
-      transferData.value = '退出请求'
-      isTransferring.value = true
-      await delay(800)
-    } else if (i === 1) {
-      serverSession.value = null
-      await delay(600)
-    } else if (i === 2) {
-      sessionCookie.value = ''
-      isLoggedIn.value = false
-      await delay(500)
-    } else {
-      await delay(400)
-    }
+  if (step.value === 4) {
+    return `GET /api/admin/users
+Cookie: session_id=${cookie.value}`
   }
+  return `POST /logout
+Cookie: session_id=${cookie.value}`
+})
 
-  isTransferring.value = false
-  currentRequest.value = ''
-  transferData.value = ''
-}
-
-const generateSessionId = () => {
-  return 'sess_' + Math.random().toString(36).substring(2, 15)
-}
-
-const delay = (ms) => {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
+const serverResponse = computed(() => {
+  if (step.value === 0) return ''
+  if (step.value === 1) return '200 OK (credentials valid)'
+  if (step.value === 2) {
+    return `200 OK
+Set-Cookie: session_id=${cookie.value}; HttpOnly; Secure; SameSite=Lax`
+  }
+  if (step.value === 3) return '200 OK (profile payload...)'
+  if (step.value === 4)
+    return '200 OK (admin data...) / 403 Forbidden (if not admin)'
+  return `200 OK
+Set-Cookie: session_id=; Max-Age=0`
+})
 </script>
 
 <style scoped>
-.session-cookie-demo {
+.session-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
 .controls {
   display: flex;
-  gap: 0.75rem;
-  margin-bottom: 1.5rem;
-  flex-wrap: wrap;
-}
-
-.action-btn {
-  flex: 1;
-  min-width: 140px;
-  padding: 0.75rem 1rem;
-  border: none;
-  border-radius: 8px;
-  cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
-  align-items: center;
-  justify-content: center;
   gap: 0.5rem;
-  font-weight: 600;
-  font-size: 0.9rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
 }
 
-.action-btn:disabled {
+.btn {
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
+
+.btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.btn:disabled {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
-.action-btn.login {
-  background: #22c55e;
-  color: white;
-}
-
-.action-btn.login:hover:not(:disabled) {
-  background: #16a34a;
-}
-
-.action-btn.request {
-  background: #3b82f6;
-  color: white;
-}
-
-.action-btn.request:hover:not(:disabled) {
-  background: #2563eb;
-}
-
-.action-btn.logout {
-  background: #ef4444;
-  color: white;
-}
-
-.action-btn.logout:hover:not(:disabled) {
-  background: #dc2626;
-}
-
-.btn-icon {
-  font-size: 1.2rem;
-}
-
-.visual-container {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.client-server {
-  display: grid;
-  grid-template-columns: 1fr auto 1fr;
-  gap: 1.5rem;
-  align-items: stretch;
-}
-
-.client,
-.server {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.device-header {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.75rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.device-icon {
-  font-size: 1.5rem;
-}
-
-.device-label {
-  font-weight: 600;
-  font-size: 0.95rem;
-}
-
-.device-content {
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.cookie-jar,
-.session-storage {
-  background: var(--vp-c-bg-soft);
-  border-radius: 8px;
-  padding: 1rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.jar-label,
-.storage-label {
-  font-weight: 600;
-  font-size: 0.85rem;
+.progress {
+  color: var(--vp-c-text-2);
+  font-size: 0.9rem;
   margin-bottom: 0.75rem;
-  color: var(--vp-c-brand);
 }
 
-.jar-content,
-.storage-content {
-  min-height: 80px;
-}
-
-.cookie-item,
-.session-item {
-  background: white;
-  border-radius: 6px;
-  padding: 0.75rem;
-  border: 1px solid var(--vp-c-divider);
-  font-family: 'Courier New', monospace;
-  font-size: 0.8rem;
-}
-
-.cookie-key {
-  font-weight: 600;
-  color: var(--vp-c-brand);
-  margin-bottom: 0.4rem;
-}
-
-.cookie-value {
-  color: var(--vp-c-text-2);
-  word-break: break-all;
-}
-
-.session-key {
-  font-weight: 600;
-  color: #8b5cf6;
-  margin-bottom: 0.5rem;
-  padding-bottom: 0.5rem;
-  border-bottom: 1px solid var(--vp-c-divider);
-}
-
-.session-data {
-  display: flex;
-  flex-direction: column;
-  gap: 0.3rem;
-}
-
-.data-row {
-  display: flex;
-  gap: 0.5rem;
-}
-
-.data-key {
-  color: var(--vp-c-brand);
-  font-weight: 600;
-}
-
-.data-value {
-  color: var(--vp-c-text-2);
-}
-
-.cookie-empty,
-.session-empty {
-  text-align: center;
-  color: var(--vp-c-text-2);
-  font-size: 0.85rem;
-  padding: 1rem;
-  font-style: italic;
-}
-
-.request-preview {
-  background: #1e293b;
-  border-radius: 6px;
-  padding: 0.75rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.preview-title {
-  font-weight: 600;
-  font-size: 0.75rem;
-  color: #94a3b8;
-  margin-bottom: 0.5rem;
-}
-
-.preview-content {
-  font-family: 'Courier New', monospace;
-  font-size: 0.75rem;
-  color: #e2e8f0;
-  line-height: 1.5;
-}
-
-.preview-line {
-  white-space: pre-wrap;
-  word-break: break-all;
-}
-
-.connection {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 1rem 0;
-}
-
-.connection-line {
-  width: 100px;
-  height: 4px;
-  background: var(--vp-c-divider);
-  border-radius: 2px;
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
-
-.connection-line.active {
-  background: linear-gradient(90deg, #3b82f6, #8b5cf6);
-}
-
-.data-packet {
-  position: absolute;
-  background: white;
-  padding: 0.4rem 0.75rem;
-  border-radius: 6px;
-  border: 2px solid var(--vp-c-brand);
-  font-size: 0.75rem;
-  font-weight: 600;
-  white-space: nowrap;
-  animation: pulse 0.5s ease-in-out infinite;
-}
-
-@keyframes pulse {
-  0%,
-  100% {
-    transform: scale(1);
-  }
-  50% {
-    transform: scale(1.05);
-  }
-}
-
-.flow-steps {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.steps-title {
-  font-weight: 700;
-  font-size: 1rem;
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
   margin-bottom: 1rem;
 }
 
-.steps-list {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.step-item {
-  display: flex;
-  gap: 0.75rem;
-  padding: 0.75rem;
-  border-radius: 8px;
-  background: var(--vp-c-bg-soft);
-  border: 1px solid var(--vp-c-divider);
-  transition: all 0.3s ease;
-}
-
-.step-item.active {
-  border-color: var(--vp-c-brand);
-  background: rgba(59, 130, 246, 0.1);
-}
-
-.step-number {
-  width: 28px;
-  height: 28px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  color: white;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  font-size: 0.85rem;
-  flex-shrink: 0;
-}
-
-.step-content {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  font-size: 0.9rem;
-}
-
-.info-cards {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-  gap: 1rem;
-}
-
-.info-card {
+.card {
   background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.25rem;
   border: 1px solid var(--vp-c-divider);
-}
-
-.card-icon {
-  font-size: 2rem;
-  margin-bottom: 0.75rem;
+  border-radius: 8px;
+  padding: 1rem;
 }
 
 .card-title {
-  font-weight: 700;
-  font-size: 1rem;
+  font-weight: 800;
+  margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
+}
+
+.box {
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
   margin-bottom: 0.75rem;
 }
 
-.card-list {
-  margin: 0;
-  padding-left: 1.25rem;
-}
-
-.card-list li {
+.box-title {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
   margin-bottom: 0.5rem;
-  font-size: 0.85rem;
-  line-height: 1.5;
+  font-size: 0.9rem;
 }
 
-.info-card.pros .card-list li {
-  color: #16a34a;
+.empty {
+  color: var(--vp-c-text-3);
+  font-style: italic;
 }
 
-.info-card.cons .card-list li {
-  color: #dc2626;
+.kv {
+  display: grid;
+  grid-template-columns: 1fr 2fr;
+  gap: 0.75rem;
+  align-items: start;
 }
 
-@media (max-width: 768px) {
-  .client-server {
-    grid-template-columns: 1fr;
-    gap: 1rem;
-  }
+.k {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+}
 
-  .connection {
-    display: none;
-  }
+.v {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
 
-  .info-cards {
+.row {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.muted {
+  color: var(--vp-c-text-3);
+  min-width: 72px;
+}
+
+.mono {
+  font-family: var(--vp-font-family-mono);
+  word-break: break-all;
+}
+
+.code {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+}
+
+.desc {
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
+
+.warn {
+  margin-top: 0.75rem;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+
+.warn-title {
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.25rem;
+}
+
+.warn-text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+@media (max-width: 720px) {
+  .grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/SessionVsJWTDemo.vue b/docs/.vitepress/theme/components/appendix/auth-design/SessionVsJWTDemo.vue
index d4756d2..6b5b93a 100644
--- a/docs/.vitepress/theme/components/appendix/auth-design/SessionVsJWTDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/auth-design/SessionVsJWTDemo.vue
@@ -1,889 +1,319 @@
 <!--
   SessionVsJWTDemo.vue
-  Session vs JWT 对比演示
+  Session vs JWT（决策辅助，更可用）
 -->
 <template>
   <div class="session-vs-jwt-demo">
     <div class="header">
-      <div class="title">Session vs JWT：全方位对比</div>
-      <div class="subtitle">两种主流鉴权方案的优劣势分析</div>
-    </div>
-
-    <div class="scenario-selector">
-      <div class="selector-title">选择场景</div>
-      <div class="scenario-buttons">
-        <button
-          v-for="scenario in scenarios"
-          :key="scenario.key"
-          class="scenario-btn"
-          :class="{ active: selectedScenario === scenario.key }"
-          @click="selectScenario(scenario.key)"
-        >
-          <span class="scenario-icon">{{ scenario.icon }}</span>
-          <span class="scenario-label">{{ scenario.label }}</span>
-        </button>
+      <div class="title">🧩 Session vs JWT：怎么选？</div>
+      <div class="subtitle">
+        选你的约束条件，得到推荐方案（并解释原因）。这比“背结论”更好用。
       </div>
     </div>
 
-    <div class="comparison-table" v-if="selectedScenario">
-      <table>
-        <thead>
-          <tr>
-            <th>对比维度</th>
-            <th class="session-col">Session + Cookie</th>
-            <th class="jwt-col">JWT</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr
-            v-for="(row, index) in getCurrentScenarioRows()"
-            :key="index"
-            :class="{ highlight: row.highlight }"
+    <div class="grid">
+      <div class="card">
+        <div class="card-title">你的场景</div>
+
+        <label class="label">主要客户端</label>
+        <div class="row">
+          <button
+            class="chip"
+            :class="{ active: client === 'web' }"
+            @click="client = 'web'"
           >
-            <td class="dimension">{{ row.dimension }}</td>
-            <td class="session-cell">
-              <div class="cell-content">
-                <span class="cell-icon">{{ row.session.icon }}</span>
-                <span class="cell-text">{{ row.session.text }}</span>
-                <span class="cell-score" :class="row.session.scoreClass">
-                  {{ row.session.score }}
-                </span>
-              </div>
-            </td>
-            <td class="jwt-cell">
-              <div class="cell-content">
-                <span class="cell-icon">{{ row.jwt.icon }}</span>
-                <span class="cell-text">{{ row.jwt.text }}</span>
-                <span class="cell-score" :class="row.jwt.scoreClass">
-                  {{ row.jwt.score }}
-                </span>
-              </div>
-            </td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
-
-    <div class="recommendation" v-if="selectedScenario">
-      <div class="rec-header">
-        <div class="rec-icon">{{ currentRecommendation.icon }}</div>
-        <div class="rec-title">{{ currentRecommendation.title }}</div>
-      </div>
-      <div class="rec-content">
-        <div class="rec-winner">
-          推荐方案：{{ currentRecommendation.winner }}
+            浏览器 Web
+          </button>
+          <button
+            class="chip"
+            :class="{ active: client === 'mobile' }"
+            @click="client = 'mobile'"
+          >
+            移动端 App
+          </button>
+          <button
+            class="chip"
+            :class="{ active: client === 'server' }"
+            @click="client = 'server'"
+          >
+            服务到服务
+          </button>
         </div>
-        <div class="rec-reason">{{ currentRecommendation.reason }}</div>
-      </div>
-    </div>
 
-    <div class="quick-guide">
-      <div class="guide-title">快速选择指南</div>
-      <div class="guide-cards">
-        <div class="guide-card session-card">
-          <div class="card-header">
-            <div class="card-icon">🍪</div>
-            <div class="card-title">选择 Session + Cookie</div>
-          </div>
-          <ul class="card-list">
-            <li>✅ 传统 Web 应用（服务器端渲染）</li>
-            <li>✅ 需要服务端主动控制用户会话</li>
-            <li>✅ 单体应用，不需要跨域</li>
-            <li>✅ 对安全性要求极高的场景</li>
+        <label class="label">是否强需求“立刻注销/踢下线”</label>
+        <div class="row">
+          <button
+            class="chip"
+            :class="{ active: revoke === 'yes' }"
+            @click="revoke = 'yes'"
+          >
+            是
+          </button>
+          <button
+            class="chip"
+            :class="{ active: revoke === 'no' }"
+            @click="revoke = 'no'"
+          >
+            否
+          </button>
+        </div>
+
+        <label class="label">是否需要跨域（前后端分离，多域名）</label>
+        <div class="row">
+          <button
+            class="chip"
+            :class="{ active: cors === 'yes' }"
+            @click="cors = 'yes'"
+          >
+            是
+          </button>
+          <button
+            class="chip"
+            :class="{ active: cors === 'no' }"
+            @click="cors = 'no'"
+          >
+            否
+          </button>
+        </div>
+
+        <label class="label">服务是否会水平扩容（多实例）</label>
+        <div class="row">
+          <button
+            class="chip"
+            :class="{ active: scale === 'yes' }"
+            @click="scale = 'yes'"
+          >
+            是
+          </button>
+          <button
+            class="chip"
+            :class="{ active: scale === 'no' }"
+            @click="scale = 'no'"
+          >
+            否
+          </button>
+        </div>
+      </div>
+
+      <div class="card">
+        <div class="card-title">推荐</div>
+        <div class="recommend">
+          <div class="pill primary">{{ recommendation.title }}</div>
+          <div class="desc">{{ recommendation.desc }}</div>
+        </div>
+
+        <div class="box">
+          <div class="box-title">为什么</div>
+          <ul class="list">
+            <li v-for="(x, i) in recommendation.reasons" :key="i">{{ x }}</li>
           </ul>
         </div>
 
-        <div class="guide-card jwt-card">
-          <div class="card-header">
-            <div class="card-icon">🎫</div>
-            <div class="card-title">选择 JWT</div>
-          </div>
-          <ul class="card-list">
-            <li>✅ 前后端分离的 SPA 应用</li>
-            <li>✅ 移动端 App（iOS/Android）</li>
-            <li>✅ 微服务架构</li>
-            <li>✅ 需要跨域访问的 API</li>
+        <div class="box">
+          <div class="box-title">落地建议</div>
+          <ul class="list">
+            <li v-for="(x, i) in recommendation.tips" :key="i">{{ x }}</li>
           </ul>
         </div>
       </div>
     </div>
 
-    <div class="architecture-comparison">
-      <div class="arch-title">架构对比</div>
-      <div class="arch-diagrams">
-        <div class="arch-item session-arch">
-          <div class="arch-label">Session 架构</div>
-          <div class="arch-content">
-            <div class="arch-step">
-              <span class="step-icon">1️⃣</span>
-              <span class="step-text">用户登录</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">2️⃣</span>
-              <span class="step-text">服务器创建 Session</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step server-storage">
-              <span class="step-icon">💾</span>
-              <span class="step-text">存储到 Redis/Memory</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">3️⃣</span>
-              <span class="step-text">返回 Cookie</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">4️⃣</span>
-              <span class="step-text">每次请求自动带上</span>
-            </div>
-          </div>
-          <div class="arch-note">有状态：需要存储 Session</div>
-        </div>
-
-        <div class="arch-item jwt-arch">
-          <div class="arch-label">JWT 架构</div>
-          <div class="arch-content">
-            <div class="arch-step">
-              <span class="step-icon">1️⃣</span>
-              <span class="step-text">用户登录</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">2️⃣</span>
-              <span class="step-text">服务器生成 JWT</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step client-storage">
-              <span class="step-icon">💾</span>
-              <span class="step-text">客户端存储 Token</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">3️⃣</span>
-              <span class="step-text">返回 Token</span>
-            </div>
-            <div class="arch-arrow">↓</div>
-            <div class="arch-step">
-              <span class="step-icon">4️⃣</span>
-              <span class="step-text">每次请求在 Header 携带</span>
-            </div>
-          </div>
-          <div class="arch-note">无状态：不存储用户会话</div>
-        </div>
-      </div>
+    <div class="card">
+      <div class="card-title">常见误区</div>
+      <ul class="list">
+        <li>
+          <strong>JWT ≠ 更安全：</strong>JWT
+          只是“无状态”。安全取决于密钥、过期策略、存储方式、授权设计。
+        </li>
+        <li>
+          <strong>Cookie ≠ 一定 CSRF：</strong>SameSite + CSRF token
+          可以显著降低风险。
+        </li>
+        <li>
+          <strong>别把第三方 OAuth token 当你系统 token：</strong>用途不同。
+        </li>
+      </ul>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 
-const selectedScenario = ref('spa')
+const client = ref('web') // web | mobile | server
+const revoke = ref('yes') // yes | no
+const cors = ref('no') // yes | no
+const scale = ref('yes') // yes | no
 
-const scenarios = [
-  { key: 'spa', label: '前后端分离', icon: '🌐' },
-  { key: 'mobile', label: '移动端', icon: '📱' },
-  { key: 'microservice', label: '微服务', icon: '🔧' },
-  { key: 'traditional', label: '传统 Web', icon: '🖥️' },
-  { key: 'security', label: '高安全需求', icon: '🔒' }
-]
+const recommendation = computed(() => {
+  // Very simple heuristic: prefer session for same-site web + revoke requirement.
+  const reasons = []
+  const tips = []
 
-const scenarioData = {
-  spa: {
-    rows: [
-      {
-        dimension: '跨域支持',
-        session: {
-          icon: '❌',
-          text: 'Cookie 无法跨域',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: 'Header 携带，完美支持',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '实现复杂度',
-        session: {
-          icon: '⚠️',
-          text: '需要处理 CORS 和 Cookie',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        jwt: {
-          icon: '✅',
-          text: '简单，localStorage + Header',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: false
-      },
-      {
-        dimension: '扩展性',
-        session: {
-          icon: '⚠️',
-          text: '有状态，扩展困难',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: '无状态，易于扩展',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '安全性',
-        session: {
-          icon: '⚠️',
-          text: '易受 CSRF 攻击',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        jwt: {
-          icon: '✅',
-          text: '天然防 CSRF',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: false
-      }
-    ],
-    recommendation: {
-      icon: '🏆',
-      title: '推荐方案',
-      winner: 'JWT',
-      reason:
-        '前后端分离架构下，JWT 的无状态特性和跨域优势使其成为最佳选择。避免 Cookie 的跨域问题，且更易于扩展。'
-    }
-  },
-  mobile: {
-    rows: [
-      {
-        dimension: '移动端支持',
-        session: {
-          icon: '⚠️',
-          text: 'Cookie 管理复杂',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: '原生支持，存储简单',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '网络开销',
-        session: {
-          icon: '✅',
-          text: '只传 session_id',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '⚠️',
-          text: 'Token 较大',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        highlight: false
-      },
-      {
-        dimension: '离线能力',
-        session: {
-          icon: '❌',
-          text: '必须联网验证',
-          score: '⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: '可离线解析基本信息',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      }
-    ],
-    recommendation: {
-      icon: '🏆',
-      title: '推荐方案',
-      winner: 'JWT',
-      reason:
-        '移动端原生应用没有浏览器的 Cookie 机制，JWT 更适合。可以轻松存储在 UserDefaults/SharedPreferences 中。'
-    }
-  },
-  microservice: {
-    rows: [
-      {
-        dimension: '服务间通信',
-        session: {
-          icon: '⚠️',
-          text: '需要共享 Session 存储',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: '直接传递 Token',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '水平扩展',
-        session: {
-          icon: '⚠️',
-          text: '需要 Redis 共享',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        jwt: {
-          icon: '✅',
-          text: '无状态，任意服务器可验证',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '性能',
-        session: {
-          icon: '⚠️',
-          text: '每次请求查 Redis',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        jwt: {
-          icon: '✅',
-          text: '直接验证签名',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: false
-      }
-    ],
-    recommendation: {
-      icon: '🏆',
-      title: '推荐方案',
-      winner: 'JWT',
-      reason:
-        '微服务架构下，JWT 的无状态特性是巨大优势。不需要在服务间共享 Session，任何服务都可以独立验证 Token。'
-    }
-  },
-  traditional: {
-    rows: [
-      {
-        dimension: '实现难度',
-        session: {
-          icon: '✅',
-          text: '框架内置支持',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '⚠️',
-          text: '需要额外集成',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        highlight: true
-      },
-      {
-        dimension: '会话管理',
-        session: {
-          icon: '✅',
-          text: '可主动注销',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '⚠️',
-          text: '无法主动注销',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        highlight: true
-      },
-      {
-        dimension: '安全性',
-        session: {
-          icon: '✅',
-          text: 'HttpOnly Cookie',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '⚠️',
-          text: 'XSS 风险',
-          score: '⭐⭐⭐',
-          scoreClass: 'medium'
-        },
-        highlight: false
-      }
-    ],
-    recommendation: {
-      icon: '🏆',
-      title: '推荐方案',
-      winner: 'Session + Cookie',
-      reason:
-        '传统 Web 应用（如 PHP、Java Web）通常有成熟的 Session 机制，实现简单且安全。主动注销功能很重要。'
-    }
-  },
-  security: {
-    rows: [
-      {
-        dimension: '防篡改',
-        session: {
-          icon: '✅',
-          text: '服务端存储，无法篡改',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '✅',
-          text: '签名防篡改',
-          score: '⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: false
-      },
-      {
-        dimension: '防 CSRF',
-        session: {
-          icon: '⚠️',
-          text: '易受攻击',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        jwt: {
-          icon: '✅',
-          text: '天然免疫',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        highlight: true
-      },
-      {
-        dimension: '防 XSS',
-        session: {
-          icon: '✅',
-          text: 'HttpOnly Cookie',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '⚠️',
-          text: 'localStorage 可被读取',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        highlight: true
-      },
-      {
-        dimension: '主动注销',
-        session: {
-          icon: '✅',
-          text: '立即删除 Session',
-          score: '⭐⭐⭐⭐⭐',
-          scoreClass: 'high'
-        },
-        jwt: {
-          icon: '❌',
-          text: '需黑名单机制',
-          score: '⭐⭐',
-          scoreClass: 'low'
-        },
-        highlight: true
-      }
-    ],
-    recommendation: {
-      icon: '⚖️',
-      title: '推荐方案',
-      winner: '视情况而定',
-      reason:
-        '高安全场景下，Session + Cookie（HttpOnly）通常更安全。但如果 CSRF 是主要威胁，JWT 可能更好。建议结合实际威胁模型选择。'
+  const isWeb = client.value === 'web'
+  const needsRevoke = revoke.value === 'yes'
+  const needsCors = cors.value === 'yes'
+  const needsScale = scale.value === 'yes'
+
+  if (isWeb && !needsCors && needsRevoke) {
+    reasons.push('同域 Web + 需要“立刻注销/踢下线” → Session 更直观可控。')
+    if (needsScale) reasons.push('多实例时用 Redis 等共享 Session 存储即可。')
+    tips.push('Cookie: HttpOnly + Secure + SameSite=Lax/Strict（视业务）')
+    tips.push('CSRF：SameSite + CSRF Token（双重保险）')
+    tips.push('Session Store：Redis + TTL + 续期策略（滑动过期）')
+    return {
+      title: 'Session + Cookie',
+      desc: '传统 Web 的最稳妥方案',
+      reasons,
+      tips
     }
   }
-}
 
-const getCurrentScenarioRows = () => {
-  return scenarioData[selectedScenario.value]?.rows || []
-}
-
-const currentRecommendation = computed(() => {
-  return (
-    scenarioData[selectedScenario.value]?.recommendation || {
-      icon: '❓',
-      title: '推荐方案',
-      winner: '未知',
-      reason: '请选择一个场景'
-    }
+  // Otherwise default to token approach.
+  reasons.push('跨域/移动端/多服务场景更偏向 Token（Authorization Header）。')
+  if (needsRevoke)
+    reasons.push(
+      '需要主动注销：用短 access token + refresh token + 黑名单/版本号。'
+    )
+  if (!needsRevoke) reasons.push('不强求“立刻注销”时，JWT 的无状态优势更明显。')
+  tips.push('Access Token：短过期（如 15m），Refresh Token：单独存/可轮换')
+  tips.push(
+    '存储：Web 尽量避免 localStorage；更推荐 HttpOnly Cookie 或内存 + 刷新机制（看业务）'
   )
+  tips.push('授权：服务端做 RBAC/ABAC；不要把 role 全塞 JWT 然后永不变更')
+  return {
+    title: 'JWT Access Token（配合 Refresh）',
+    desc: '现代 API/移动端常用组合',
+    reasons,
+    tips
+  }
 })
-
-const selectScenario = (key) => {
-  selectedScenario.value = key
-}
 </script>
 
 <style scoped>
 .session-vs-jwt-demo {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 1.5rem;
-  margin: 1.5rem 0;
-  font-family: var(--vp-font-family-base);
+  margin: 1rem 0;
 }
 
 .header {
-  margin-bottom: 1.5rem;
+  margin-bottom: 1rem;
 }
 
 .title {
-  font-weight: 700;
-  font-size: 1.1rem;
-  margin-bottom: 0.3rem;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
 }
 
 .subtitle {
+  margin-top: 0.25rem;
   color: var(--vp-c-text-2);
   font-size: 0.9rem;
 }
 
-.scenario-selector {
-  margin-bottom: 1.5rem;
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin-bottom: 1rem;
 }
 
-.selector-title {
-  font-weight: 600;
-  font-size: 0.95rem;
+.card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
+}
+
+.card-title {
+  font-weight: 800;
   margin-bottom: 0.75rem;
+  color: var(--vp-c-text-1);
 }
 
-.scenario-buttons {
+.label {
+  display: block;
+  font-weight: 800;
+  color: var(--vp-c-text-1);
+  font-size: 0.875rem;
+  margin: 0.75rem 0 0.35rem;
+}
+
+.row {
   display: flex;
   gap: 0.5rem;
   flex-wrap: wrap;
 }
 
-.scenario-btn {
-  flex: 1;
-  min-width: 100px;
-  padding: 0.75rem 1rem;
-  border: 2px solid var(--vp-c-divider);
-  border-radius: 8px;
+.chip {
+  padding: 0.4rem 0.65rem;
+  border-radius: 999px;
+  border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
   cursor: pointer;
-  transition: all 0.2s ease;
-  display: flex;
+  font-weight: 700;
+  font-size: 0.875rem;
+}
+
+.chip.active {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.recommend {
+  margin-bottom: 0.75rem;
+}
+
+.pill {
+  display: inline-flex;
   align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  font-size: 0.9rem;
-}
-
-.scenario-btn:hover {
-  border-color: var(--vp-c-brand);
-}
-
-.scenario-btn.active {
-  background: var(--vp-c-brand);
-  color: white;
-  border-color: var(--vp-c-brand);
-}
-
-.scenario-icon {
-  font-size: 1.2rem;
-}
-
-.comparison-table {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
+  border-radius: 999px;
+  padding: 0.25rem 0.75rem;
   border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-  overflow-x: auto;
-}
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-}
-
-thead th {
-  padding: 0.75rem;
-  text-align: left;
-  font-weight: 700;
-  font-size: 0.9rem;
-  border-bottom: 2px solid var(--vp-c-divider);
-}
-
-thead th.session-col {
-  color: #f59e0b;
-}
-
-thead th.jwt-col {
-  color: #8b5cf6;
-}
-
-tbody tr {
-  border-bottom: 1px solid var(--vp-c-divider);
-}
-
-tbody tr:last-child {
-  border-bottom: none;
-}
-
-tbody tr.highlight {
-  background: rgba(59, 130, 246, 0.05);
-}
-
-.dimension {
-  padding: 0.75rem;
-  font-weight: 600;
-  font-size: 0.85rem;
-}
-
-.cell-content {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.5rem;
-}
-
-.cell-icon {
-  font-size: 1.2rem;
-  flex-shrink: 0;
-}
-
-.cell-text {
-  flex: 1;
-  font-size: 0.85rem;
-}
-
-.cell-score {
-  font-size: 0.85rem;
-  font-weight: 700;
-}
-
-.cell-score.high {
-  color: #22c55e;
-}
-
-.cell-score.medium {
-  color: #f59e0b;
-}
-
-.cell-score.low {
-  color: #ef4444;
-}
-
-.recommendation {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 2px solid var(--vp-c-brand);
-  margin-bottom: 1.5rem;
-}
-
-.rec-header {
-  display: flex;
-  align-items: center;
-  gap: 0.75rem;
-  margin-bottom: 1rem;
-}
-
-.rec-icon {
-  font-size: 2rem;
-}
-
-.rec-title {
-  font-size: 1.1rem;
-  font-weight: 700;
-}
-
-.rec-content {
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-.rec-winner {
-  font-size: 1rem;
-  font-weight: 700;
-  color: var(--vp-c-brand);
-}
-
-.rec-reason {
-  font-size: 0.9rem;
-  line-height: 1.6;
+  background: var(--vp-c-bg-alt);
   color: var(--vp-c-text-2);
-}
-
-.quick-guide {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
-  margin-bottom: 1.5rem;
-}
-
-.guide-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.guide-cards {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
-  gap: 1rem;
-}
-
-.guide-card {
-  background: var(--vp-c-bg-soft);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.card-header {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  margin-bottom: 1rem;
-}
-
-.card-icon {
-  font-size: 1.5rem;
-}
-
-.card-title {
-  font-weight: 700;
-  font-size: 0.95rem;
-}
-
-.card-list {
-  margin: 0;
-  padding-left: 1.25rem;
-}
-
-.card-list li {
+  font-weight: 800;
   margin-bottom: 0.5rem;
-  font-size: 0.85rem;
-  line-height: 1.5;
 }
 
-.architecture-comparison {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1.5rem;
-  border: 1px solid var(--vp-c-divider);
+.pill.primary {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  background: rgba(var(--vp-c-brand-rgb), 0.1);
+  color: var(--vp-c-text-1);
 }
 
-.arch-title {
-  font-weight: 700;
-  font-size: 1rem;
-  margin-bottom: 1rem;
-}
-
-.arch-diagrams {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-  gap: 1.5rem;
-}
-
-.arch-item {
-  background: var(--vp-c-bg-soft);
-  border-radius: 10px;
-  padding: 1.25rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.arch-label {
-  font-weight: 700;
-  font-size: 0.95rem;
-  margin-bottom: 1rem;
-  text-align: center;
-  color: var(--vp-c-brand);
-}
-
-.arch-content {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.arch-step {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.5rem;
-  background: white;
-  border-radius: 6px;
-  font-size: 0.85rem;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.step-icon {
-  font-size: 1.2rem;
-  flex-shrink: 0;
-}
-
-.step-text {
-  flex: 1;
-}
-
-.arch-arrow {
-  text-align: center;
-  font-size: 1.2rem;
+.desc {
   color: var(--vp-c-text-2);
-  font-weight: 700;
+  line-height: 1.75;
 }
 
-.server-storage,
-.client-storage {
-  border-color: #f59e0b;
-  background: rgba(245, 158, 11, 0.1);
-}
-
-.arch-note {
-  margin-top: 1rem;
-  text-align: center;
-  font-size: 0.8rem;
-  font-weight: 600;
-  color: var(--vp-c-text-2);
-  padding: 0.5rem;
-  background: white;
-  border-radius: 6px;
+.box {
   border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  padding: 0.75rem;
+  margin-top: 0.75rem;
 }
 
-@media (max-width: 768px) {
-  .scenario-buttons {
-    flex-direction: column;
-  }
+.box-title {
+  font-weight: 800;
+  margin-bottom: 0.5rem;
+  color: var(--vp-c-text-1);
+}
 
-  .guide-cards {
-    grid-template-columns: 1fr;
-  }
+.list {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.75;
+}
 
-  .arch-diagrams {
+@media (max-width: 720px) {
+  .grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/shared/components.js b/docs/.vitepress/theme/components/appendix/auth-design/shared/components.js
new file mode 100644
index 0000000..52d89bd
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/auth-design/shared/components.js
@@ -0,0 +1,134 @@
+// auth-design 公共组件配置
+
+// 生成按钮类名
+export const getButtonClasses = (variant = 'primary', disabled = false, size = 'medium') => {
+  const base = 'auth-demo-btn'
+  const classes = [base]
+
+  // 变体
+  classes.push(`${base}-${variant}`)
+
+  // 状态
+  if (disabled) classes.push(`${base}-disabled`)
+
+  // 大小
+  classes.push(`${base}-${size}`)
+
+  return classes.join(' ')
+}
+
+// 生成卡片类名
+export const getCardClasses = (variant = 'default', clickable = false) => {
+  const base = 'auth-demo-card'
+  const classes = [base]
+
+  if (variant !== 'default') {
+    classes.push(`${base}-${variant}`)
+  }
+
+  if (clickable) {
+    classes.push(`${base}-clickable`)
+  }
+
+  return classes.join(' ')
+}
+
+// 生成状态徽章类名
+export const getBadgeClasses = (type = 'info') => {
+  const types = {
+    success: 'auth-badge-success',
+    warning: 'auth-badge-warning',
+    danger: 'auth-badge-danger',
+    info: 'auth-badge-info',
+    purple: 'auth-badge-purple'
+  }
+
+  return types[type] || types.info
+}
+
+// 生成进度条类名
+export const getProgressClasses = (variant = 'primary') => {
+  return `auth-progress auth-progress-${variant}`
+}
+
+// 格式化代码示例
+export const formatCodeExample = (code, language = 'javascript') => {
+  if (typeof code !== 'string') return ''
+  return code.trim()
+}
+
+// 生成流程步骤类名
+export const getStepClasses = (index, currentIndex, totalSteps) => {
+  const classes = ['auth-step']
+
+  if (index < currentIndex) {
+    classes.push('auth-step-completed')
+  } else if (index === currentIndex) {
+    classes.push('auth-step-active')
+  } else {
+    classes.push('auth-step-pending')
+  }
+
+  return classes.join(' ')
+}
+
+// 生成表格行类名
+export const getTableRowClasses = (highlight = false, index = 0) => {
+  const classes = ['auth-table-row']
+
+  if (highlight) classes.push('auth-table-row-highlight')
+  if (index % 2 === 0) classes.push('auth-table-row-even')
+
+  return classes.join(' ')
+}
+
+// 生成图标容器类名
+export const getIconContainerClasses = (size = 'medium', variant = 'default') => {
+  return `auth-icon-container auth-icon-container-${size} auth-icon-container-${variant}`
+}
+
+// 生成输入框类名
+export const getInputClasses = (state = 'default', size = 'medium') => {
+  const classes = ['auth-input']
+
+  if (state !== 'default') {
+    classes.push(`auth-input-${state}`)
+  }
+
+  if (size !== 'medium') {
+    classes.push(`auth-input-${size}`)
+  }
+
+  return classes.join(' ')
+}
+
+// 生成通知/提示框类名
+export const getAlertClasses = (type = 'info', dismissible = false) => {
+  const classes = ['auth-alert', `auth-alert-${type}`]
+
+  if (dismissible) {
+    classes.push('auth-alert-dismissible')
+  }
+
+  return classes.join(' ')
+}
+
+// 生成标签类名
+export const getTagClasses = (variant = 'default', size = 'medium') => {
+  return `auth-tag auth-tag-${variant} auth-tag-${size}`
+}
+
+// 生成加载器类名
+export const getSpinnerClasses = (size = 'medium') => {
+  return `auth-spinner auth-spinner-${size}`
+}
+
+// 生成下拉菜单类名
+export const getDropdownClasses = (isOpen = false, direction = 'down') => {
+  const classes = ['auth-dropdown']
+
+  if (isOpen) classes.push('auth-dropdown-open')
+  classes.push(`auth-dropdown-${direction}`)
+
+  return classes.join(' ')
+}
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/shared/composables.js b/docs/.vitepress/theme/components/appendix/auth-design/shared/composables.js
new file mode 100644
index 0000000..609493a
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/auth-design/shared/composables.js
@@ -0,0 +1,233 @@
+// auth-design 公共组合式函数
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+
+/**
+ * 延迟函数
+ * @param {number} ms - 延迟毫秒数
+ * @returns {Promise<void>}
+ */
+export const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * 防抖函数
+ * @param {Function} fn - 要防抖的函数
+ * @param {number} wait - 等待时间（毫秒）
+ * @returns {Function}
+ */
+export const useDebounce = (fn, wait = 300) => {
+  let timeout = null
+  return (...args) => {
+    clearTimeout(timeout)
+    timeout = setTimeout(() => fn(...args), wait)
+  }
+}
+
+/**
+ * 步骤流程管理
+ * @param {Array} steps - 步骤数组
+ * @param {number} stepDelay - 每步延迟时间
+ * @returns {Object}
+ */
+export const useStepFlow = (steps, stepDelay = 800) => {
+  const currentStep = ref(0)
+  const isProcessing = ref(false)
+
+  const startFlow = async () => {
+    isProcessing.value = true
+    for (let i = 0; i < steps.length; i++) {
+      currentStep.value = i + 1
+      await delay(stepDelay)
+    }
+    isProcessing.value = false
+  }
+
+  const resetFlow = () => {
+    currentStep.value = 0
+    isProcessing.value = false
+  }
+
+  return {
+    currentStep,
+    isProcessing,
+    startFlow,
+    resetFlow
+  }
+}
+
+/**
+ * 异步操作状态管理
+ * @returns {Object}
+ */
+export const useAsyncState = () => {
+  const isLoading = ref(false)
+  const error = ref(null)
+  const data = ref(null)
+
+  const execute = async (fn) => {
+    isLoading.value = true
+    error.value = null
+    try {
+      const result = await fn()
+      data.value = result
+      return result
+    } catch (err) {
+      error.value = err
+      throw err
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  const reset = () => {
+    isLoading.value = false
+    error.value = null
+    data.value = null
+  }
+
+  return {
+    isLoading,
+    error,
+    data,
+    execute,
+    reset
+  }
+}
+
+/**
+ * 定时器管理
+ * @returns {Object}
+ */
+export const useTimer = () => {
+  const timer = ref(null)
+  const isRunning = ref(false)
+
+  const start = (callback, interval) => {
+    if (timer.value) clearInterval(timer.value)
+    isRunning.value = true
+    timer.value = setInterval(callback, interval)
+  }
+
+  const stop = () => {
+    if (timer.value) {
+      clearInterval(timer.value)
+      timer.value = null
+      isRunning.value = false
+    }
+  }
+
+  onUnmounted(() => {
+    stop()
+  })
+
+  return {
+    isRunning,
+    start,
+    stop
+  }
+}
+
+/**
+ * 切换状态
+ * @param {boolean} initialValue - 初始值
+ * @returns {Object}
+ */
+export const useToggle = (initialValue = false) => {
+  const value = ref(initialValue)
+
+  const toggle = () => {
+    value.value = !value.value
+  }
+
+  const setTrue = () => {
+    value.value = true
+  }
+
+  const setFalse = () => {
+    value.value = false
+  }
+
+  return {
+    value,
+    toggle,
+    setTrue,
+    setFalse
+  }
+}
+
+/**
+ * 动画控制
+ * @param {number} duration - 动画持续时间（毫秒）
+ * @returns {Object}
+ */
+export const useAnimation = (duration = 300) => {
+  const isAnimating = ref(false)
+
+  const animate = async (callback) => {
+    isAnimating.value = true
+    await callback()
+    await delay(duration)
+    isAnimating.value = false
+  }
+
+  return {
+    isAnimating,
+    animate
+  }
+}
+
+/**
+ * 生成随机 ID
+ * @param {string} prefix - 前缀
+ * @returns {string}
+ */
+export const generateId = (prefix = 'id') => {
+  return `${prefix}_${Math.random().toString(36).substring(2, 15)}`
+}
+
+/**
+ * 格式化时间戳
+ * @param {number} timestamp - 时间戳
+ * @returns {string}
+ */
+export const formatTimestamp = (timestamp) => {
+  const date = new Date(timestamp)
+  return date.toLocaleTimeString()
+}
+
+/**
+ * 深拷贝对象
+ * @param {*} obj - 要拷贝的对象
+ * @returns {*}
+ */
+export const deepClone = (obj) => {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (obj instanceof Date) return new Date(obj.getTime())
+  if (obj instanceof Array) return obj.map((item) => deepClone(item))
+  if (obj instanceof Object) {
+    const clonedObj = {}
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        clonedObj[key] = deepClone(obj[key])
+      }
+    }
+    return clonedObj
+  }
+}
+
+/**
+ * 批量更新状态
+ * @param {Object} stateRef - 状态引用
+ * @param {Object} updates - 更新内容
+ */
+export const batchUpdate = (stateRef, updates) => {
+  Object.assign(stateRef.value, updates)
+}
+
+/**
+ * 评分转换为星星
+ * @param {number} score - 评分 (1-5)
+ * @returns {string}
+ */
+export const scoreToStars = (score) => {
+  return '⭐'.repeat(Math.floor(score))
+}
diff --git a/docs/.vitepress/theme/components/appendix/auth-design/shared/styles.js b/docs/.vitepress/theme/components/appendix/auth-design/shared/styles.js
new file mode 100644
index 0000000..a4ba190
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/auth-design/shared/styles.js
@@ -0,0 +1,144 @@
+// auth-design 公共样式配置
+export const commonStyles = {
+  // 容器样式
+  container: {
+    base: 'auth-demo-container',
+    classes: {
+      border: '1px solid var(--vp-c-divider)',
+      background: 'var(--vp-c-bg-soft)',
+      borderRadius: '12px',
+      padding: '1.5rem',
+      margin: '1.5rem 0',
+      fontFamily: 'var(--vp-font-family-base)'
+    }
+  },
+
+  // 标题样式
+  header: {
+    title: {
+      fontWeight: '700',
+      fontSize: '1.2rem',
+      marginBottom: '0.3rem',
+      background: 'linear-gradient(120deg, var(--vp-c-brand), #9c27b0)',
+      WebkitBackgroundClip: 'text',
+      WebkitTextFillColor: 'transparent'
+    },
+    subtitle: {
+      color: 'var(--vp-c-text-2)',
+      fontSize: '0.9rem'
+    }
+  },
+
+  // 按钮样式
+  button: {
+    base: 'auth-demo-btn',
+    primary: 'auth-demo-btn-primary',
+    variants: {
+      primary: {
+        background: 'var(--vp-c-brand)',
+        color: 'white'
+      },
+      success: {
+        background: '#22c55e',
+        color: 'white'
+      },
+      danger: {
+        background: '#ef4444',
+        color: 'white'
+      },
+      secondary: {
+        background: '#64748b',
+        color: 'white'
+      }
+    }
+  },
+
+  // 卡片样式
+  card: {
+    base: 'auth-demo-card',
+    background: 'var(--vp-c-bg)',
+    border: '1px solid var(--vp-c-divider)',
+    borderRadius: '10px',
+    padding: '1.25rem'
+  },
+
+  // 代码块样式
+  codeBlock: {
+    background: '#1e293b',
+    color: '#e2e8f0',
+    fontFamily: "'Courier New', monospace",
+    fontSize: '0.8rem',
+    lineHeight: '1.6',
+    padding: '0.75rem',
+    borderRadius: '6px'
+  }
+}
+
+// 动画配置
+export const animations = {
+  fadeIn: {
+    name: 'fadeIn',
+    css: `
+      @keyframes fadeIn {
+        from { opacity: 0; }
+        to { opacity: 1; }
+      }
+    `
+  },
+  slideIn: {
+    name: 'slideIn',
+    css: `
+      @keyframes slideIn {
+        from {
+          opacity: 0;
+          transform: translateY(10px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+    `
+  },
+  pulse: {
+    name: 'pulse',
+    css: `
+      @keyframes pulse {
+        0%, 100% { transform: scale(1); }
+        50% { transform: scale(1.05); }
+      }
+    `
+  },
+  bounce: {
+    name: 'bounce',
+    css: `
+      @keyframes bounce {
+        0%, 100% { transform: translateX(-50%) translateY(0); }
+        50% { transform: translateX(-50%) translateY(-5px); }
+      }
+    `
+  },
+  spin: {
+    name: 'spin',
+    css: `
+      @keyframes spin {
+        from { transform: rotate(0deg); }
+        to { transform: rotate(360deg); }
+      }
+    `
+  }
+}
+
+// 颜色配置
+export const colors = {
+  success: '#22c55e',
+  warning: '#f59e0b',
+  danger: '#ef4444',
+  info: '#3b82f6',
+  purple: '#8b5cf6'
+}
+
+// 响应式断点
+export const breakpoints = {
+  mobile: '768px'
+}
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitBranchMergeDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitBranchMergeDemo.vue
index 8cf4d5f..cbd52bd 100644
--- a/docs/.vitepress/theme/components/appendix/git-intro/GitBranchMergeDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitBranchMergeDemo.vue
@@ -2,12 +2,25 @@
   <div class="branch-demo">
     <div class="panel">
       <div class="controls">
-        <button @click="init" :disabled="inited" class="btn">初始化</button>
-        <button @click="commit" :disabled="!inited" class="btn">提交</button>
+        <button @click="init" :disabled="inited || mergePending" class="btn">
+          初始化
+        </button>
+        <button @click="commit" :disabled="!inited || mergePending" class="btn">
+          提交
+        </button>
         <button @click="branch" :disabled="!inited || hasBranch" class="btn">
           创建分支
         </button>
-        <button @click="merge" :disabled="!hasBranch" class="btn">合并</button>
+        <button
+          @click="prepareMerge"
+          :disabled="!hasBranch || mergePending"
+          class="btn"
+        >
+          准备合并
+        </button>
+        <button @click="finishMerge" :disabled="!mergePending" class="btn">
+          完成合并
+        </button>
         <button @click="reset" class="btn secondary">重置</button>
       </div>
 
@@ -72,6 +85,7 @@
 import { ref } from 'vue'
 const inited = ref(false)
 const hasBranch = ref(false)
+const mergePending = ref(false)
 const main = ref([])
 const feat = ref([])
 
@@ -88,16 +102,21 @@ const branch = () => {
     feat.value = [1]
   }
 }
-const merge = () => {
-  if (hasBranch.value) {
-    main.value.push(1)
-    hasBranch.value = false
-    feat.value = []
-  }
+const prepareMerge = () => {
+  if (!hasBranch.value) return
+  mergePending.value = true
+}
+const finishMerge = () => {
+  if (!mergePending.value) return
+  main.value.push(1)
+  hasBranch.value = false
+  feat.value = []
+  mergePending.value = false
 }
 const reset = () => {
   inited.value = false
   hasBranch.value = false
+  mergePending.value = false
   main.value = []
   feat.value = []
 }
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitCommandDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitCommandDemo.vue
index 4985538..be152a2 100644
--- a/docs/.vitepress/theme/components/appendix/git-intro/GitCommandDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitCommandDemo.vue
@@ -8,33 +8,56 @@
             <span v-html="line.text"></span>
           </div>
           <div v-if="output.length === 0" class="welcome">
-            输入命令开始学习 Git
+            输入命令开始学习 Git（建议先点“制造改动”，再跑 git status）
           </div>
         </div>
         <div class="input-line">
           <span class="prompt">$</span>
           <input
             v-model="cmd"
-            @keyup.enter="execute"
-            placeholder="git status"
+            @keyup.enter="execute({ fromQuick: false })"
+            placeholder="（默认安全模式）请用下方按钮执行命令"
             class="cmd-input"
+            :disabled="!freeMode"
           />
-          <button @click="execute" class="run-btn">运行</button>
+          <button
+            @click="execute({ fromQuick: false })"
+            class="run-btn"
+            :disabled="!freeMode"
+          >
+            运行
+          </button>
+          <button @click="clearOutput" class="run-btn secondary">清空</button>
+          <button @click="toggleFreeMode" class="run-btn secondary">
+            {{ freeMode ? '切回安全模式' : '开启自由模式' }}
+          </button>
         </div>
       </div>
 
       <div class="quick-cmds">
-        <button @click="runCmd('git init')" class="cmd-btn">初始化</button>
-        <button @click="runCmd('git status')" class="cmd-btn">状态</button>
-        <button @click="runCmd('git add .')" class="cmd-btn">添加</button>
-        <button @click="runCmd('git commit -m \'msg\'')" class="cmd-btn">
-          提交
+        <button @click="makeChanges" class="cmd-btn">制造改动</button>
+        <button @click="runCmd('git init')" class="cmd-btn">git init</button>
+        <button @click="runCmd('git status')" class="cmd-btn">
+          git status
+        </button>
+        <button @click="runCmd('git add .')" class="cmd-btn">git add .</button>
+        <button @click="runCmd(`git commit -m 'msg'`)" class="cmd-btn">
+          git commit
+        </button>
+        <button @click="runCmd('git log --oneline')" class="cmd-btn">
+          git log
+        </button>
+        <button @click="runCmd('git switch -c feat/demo')" class="cmd-btn">
+          新分支
         </button>
       </div>
     </div>
 
     <div class="info-box">
-      <p><strong>💡 常用命令:</strong> init → status → add → commit</p>
+      <p>
+        <strong>💡 建议练习顺序:</strong> 制造改动 → status → add → status →
+        commit → log
+      </p>
     </div>
   </div>
 </template>
@@ -44,29 +67,202 @@ import { ref } from 'vue'
 
 const cmd = ref('')
 const output = ref([])
+const freeMode = ref(false)
+
+// Minimal in-memory git state for learning purposes.
+const state = ref({
+  inited: false,
+  branch: 'main',
+  commits: { main: [] },
+  working: [], // modified files (not staged)
+  staged: [] // staged files
+})
+
+const pushLine = (type, text) => {
+  output.value.push({ type, text: escapeHtml(text).replace(/\n/g, '<br />') })
+  // keep the terminal from growing forever
+  if (output.value.length > 60) output.value.splice(0, output.value.length - 60)
+}
+
+const escapeHtml = (s) =>
+  s
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('\"', '&quot;')
+    .replaceAll("'", '&#039;')
+
+const genHash = () => Math.random().toString(16).slice(2, 9)
+
+const ensureRepo = () => {
+  if (!state.value.inited) {
+    pushLine(
+      'error',
+      'fatal: not a git repository (or any of the parent directories): .git'
+    )
+    return false
+  }
+  return true
+}
+
+const statusText = () => {
+  const s = state.value
+  const lines = [`On branch ${s.branch}`]
+  if (s.staged.length === 0 && s.working.length === 0) {
+    lines.push('nothing to commit, working tree clean')
+    return lines.join('\n')
+  }
+  if (s.staged.length) {
+    lines.push('Changes to be committed:')
+    s.staged.forEach((f) => lines.push(`  modified:   ${f}`))
+  }
+  if (s.working.length) {
+    lines.push('Changes not staged for commit:')
+    s.working.forEach((f) => lines.push(`  modified:   ${f}`))
+  }
+  return lines.join('\n')
+}
+
+const logText = () => {
+  const s = state.value
+  const list = s.commits[s.branch] || []
+  if (!list.length)
+    return 'fatal: your current branch does not have any commits yet'
+  return list
+    .slice()
+    .reverse()
+    .slice(0, 8)
+    .map((c) => `${c.hash} ${c.msg}`)
+    .join('\n')
+}
+
+const branchText = () => {
+  const s = state.value
+  return Object.keys(s.commits)
+    .sort()
+    .map((b) => (b === s.branch ? `* ${b}` : `  ${b}`))
+    .join('\n')
+}
+
+const makeChanges = () => {
+  if (!state.value.inited) {
+    pushLine('info', '提示：先 git init，再制造改动效果更真实。')
+    return
+  }
+  const base = ['src/app.js', 'README.md', 'src/utils.js']
+  state.value.working = base.slice(0, 1 + Math.floor(Math.random() * 3))
+  // staged changes are independent
+  pushLine(
+    'success',
+    `Edited ${state.value.working.length} file(s) (simulated).`
+  )
+}
+
+const execute = ({ fromQuick }) => {
+  if (!freeMode.value && !fromQuick) {
+    pushLine(
+      'info',
+      '当前是安全模式：请用下方按钮执行预设命令，避免“想当然”操作造成误解。'
+    )
+    cmd.value = ''
+    return
+  }
 
-const execute = () => {
   const c = cmd.value.trim()
   if (!c) return
 
-  output.value.push({ type: 'command', text: c })
+  pushLine('command', c)
 
+  // Commands
   if (c === 'git init') {
-    output.value.push({
-      type: 'success',
-      text: 'Initialized empty Git repository'
-    })
+    state.value.inited = true
+    state.value.branch = 'main'
+    state.value.commits = { main: [] }
+    state.value.working = []
+    state.value.staged = []
+    pushLine('success', 'Initialized empty Git repository in ./.git/')
   } else if (c === 'git status') {
-    output.value.push({
-      type: 'info',
-      text: 'On branch main\nnothing to commit'
+    if (!ensureRepo()) return
+    pushLine('info', statusText())
+  } else if (c === 'git add .' || c.startsWith('git add ')) {
+    if (!ensureRepo()) return
+    const s = state.value
+    if (s.working.length === 0) {
+      pushLine('info', 'Nothing specified, nothing added.')
+      return
+    }
+    const toStage =
+      c === 'git add .'
+        ? [...s.working]
+        : [c.replace(/^git add\s+/, '').trim()].filter(Boolean)
+    toStage.forEach((f) => {
+      if (!s.staged.includes(f)) s.staged.push(f)
+      s.working = s.working.filter((x) => x !== f)
     })
-  } else if (c === 'git add .') {
-    output.value.push({ type: 'success', text: 'Files added to staging area' })
+    pushLine('success', `Added ${toStage.length} path(s) to staging area.`)
   } else if (c.startsWith('git commit')) {
-    output.value.push({ type: 'success', text: '1 file committed' })
+    if (!ensureRepo()) return
+    const s = state.value
+    if (s.staged.length === 0) {
+      pushLine('error', 'nothing to commit (no changes added to commit)')
+      return
+    }
+    const msgMatch = c.match(/-m\\s+\"([^\"]+)\"|-m\\s+'([^']+)'/)
+    const msg = msgMatch?.[1] || msgMatch?.[2] || 'commit'
+    const commit = { hash: genHash(), msg, files: [...s.staged] }
+    if (!s.commits[s.branch]) s.commits[s.branch] = []
+    s.commits[s.branch].push(commit)
+    s.staged = []
+    pushLine(
+      'success',
+      `[${s.branch} ${commit.hash}] ${msg}\\n ${commit.files.length} file(s) changed`
+    )
+  } else if (c === 'git log --oneline') {
+    if (!ensureRepo()) return
+    pushLine('info', logText())
+  } else if (c === 'git branch') {
+    if (!ensureRepo()) return
+    pushLine('info', branchText())
+  } else if (
+    c.startsWith('git switch -c ') ||
+    c.startsWith('git checkout -b ')
+  ) {
+    if (!ensureRepo()) return
+    const name = c.replace(/^git (switch -c|checkout -b)\s+/, '').trim()
+    if (!name) {
+      pushLine('error', 'fatal: you must specify a branch name')
+      return
+    }
+    if (state.value.commits[name]) {
+      pushLine('error', `fatal: A branch named '${name}' already exists.`)
+      return
+    }
+    const base = state.value.commits[state.value.branch] || []
+    state.value.commits[name] = [...base]
+    state.value.branch = name
+    pushLine('success', `Switched to a new branch '${name}'`)
+  } else if (c.startsWith('git switch ') || c.startsWith('git checkout ')) {
+    if (!ensureRepo()) return
+    const name = c.replace(/^git (switch|checkout)\s+/, '').trim()
+    if (!state.value.commits[name]) {
+      pushLine(
+        'error',
+        `error: pathspec '${name}' did not match any file(s) known to git`
+      )
+      return
+    }
+    state.value.branch = name
+    pushLine('success', `Switched to branch '${name}'`)
+  } else if (c.startsWith('git restore')) {
+    if (!ensureRepo()) return
+    // Simplified restore for learning: clear working changes
+    state.value.working = []
+    pushLine('success', 'Restored working tree (simulated).')
   } else {
-    output.value.push({ type: 'error', text: 'Unknown command' })
+    pushLine(
+      'error',
+      'Unknown command (supported: init/status/add/commit/log/branch/switch/checkout/restore)'
+    )
   }
 
   cmd.value = ''
@@ -74,7 +270,22 @@ const execute = () => {
 
 const runCmd = (c) => {
   cmd.value = c
-  execute()
+  execute({ fromQuick: true })
+}
+
+const clearOutput = () => {
+  output.value = []
+}
+
+const toggleFreeMode = () => {
+  freeMode.value = !freeMode.value
+  cmd.value = ''
+  pushLine(
+    'info',
+    freeMode.value
+      ? '已开启自由模式：现在可以手动输入命令（仍然只模拟，不会影响真实仓库）。'
+      : '已切回安全模式：请使用下方按钮执行预设命令。'
+  )
 }
 </script>
 
@@ -88,33 +299,34 @@ const runCmd = (c) => {
 }
 
 .terminal {
-  background: #1f2937;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
   padding: 1rem;
   margin-bottom: 1rem;
-  font-family: monospace;
+  font-family: var(--vp-font-family-mono);
 }
 
 .output {
   min-height: 150px;
   margin-bottom: 1rem;
-  color: #d1d5db;
+  color: var(--vp-c-text-1);
 }
 
 .output .command {
-  color: #10b981;
+  color: var(--vp-c-text-1);
 }
 .output .success {
-  color: #10b981;
+  color: var(--vp-c-text-1);
 }
 .output .error {
-  color: #ef4444;
+  color: var(--vp-c-red-1, #ef4444);
 }
 .output .info {
-  color: #60a5fa;
+  color: var(--vp-c-text-2);
 }
 .output .welcome {
-  color: #9ca3af;
+  color: var(--vp-c-text-2);
   font-style: italic;
 }
 
@@ -125,32 +337,42 @@ const runCmd = (c) => {
 }
 
 .prompt {
-  color: #10b981;
+  color: var(--vp-c-brand);
 }
 
 .cmd-input {
   flex: 1;
-  background: transparent;
-  border: none;
-  color: #d1d5db;
-  font-family: monospace;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-1);
+  font-family: var(--vp-font-family-mono);
   font-size: 0.875rem;
+  border-radius: 6px;
+  padding: 0.35rem 0.5rem;
 }
 
 .cmd-input:focus {
   outline: none;
+  border-color: rgba(var(--vp-c-brand-rgb), 0.45);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
 }
 
 .run-btn {
-  padding: 0.25rem 0.75rem;
-  background: #10b981;
-  color: white;
-  border: none;
+  padding: 0.35rem 0.75rem;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-brand);
   border-radius: 4px;
   cursor: pointer;
   font-size: 0.75rem;
 }
 
+.run-btn.secondary {
+  background: var(--vp-c-bg);
+  border-color: var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+}
+
 .quick-cmds {
   display: flex;
   gap: 0.5rem;
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitRemoteDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitRemoteDemo.vue
index 037e48e..b90b547 100644
--- a/docs/.vitepress/theme/components/appendix/git-intro/GitRemoteDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitRemoteDemo.vue
@@ -4,6 +4,10 @@
       <div class="repos">
         <div class="repo">
           <div class="header">💻 本地</div>
+          <div class="meta">
+            <span class="badge">main</span>
+            <span class="hint"> Ahead {{ ahead }} / Behind {{ behind }} </span>
+          </div>
           <div class="commits">
             <div v-for="c in local" :key="c" class="commit-dot">
               <span class="dot local"></span>
@@ -17,6 +21,10 @@
 
         <div class="repo">
           <div class="header">☁️ 远程</div>
+          <div class="meta">
+            <span class="badge">origin/main</span>
+            <span class="hint">模拟队友提交在这里发生</span>
+          </div>
           <div class="commits">
             <div v-for="c in remote" :key="c" class="commit-dot">
               <span class="dot remote"></span>
@@ -29,22 +37,26 @@
 
       <div class="controls">
         <button @click="localCommit" class="btn">本地提交</button>
+        <button @click="remoteCommit" class="btn">远程新增提交</button>
         <button
           @click="push"
           :disabled="local.length <= remote.length"
           class="btn"
         >
-          推送 Push
+          git push
         </button>
-        <button @click="pull" :disabled="!hasRemote" class="btn">
-          拉取 Pull
+        <button @click="pull" :disabled="behind === 0" class="btn">
+          git pull
         </button>
         <button @click="reset" class="btn secondary">重置</button>
       </div>
     </div>
 
     <div class="info-box">
-      <p><strong>💡 远程协作:</strong> Push 上传，Pull 下载，保持同步</p>
+      <p>
+        <strong>💡 远程协作:</strong> 你本地落后（Behind）就
+        pull，你本地领先（Ahead）就 push。
+      </p>
     </div>
   </div>
 </template>
@@ -53,23 +65,33 @@
 import { ref, computed } from 'vue'
 const local = ref([])
 const remote = ref([])
-const hasRemote = ref(false)
 
 const localCommit = () => {
   local.value.push(Math.random().toString(16).substr(2, 7))
 }
+
+const remoteCommit = () => {
+  remote.value.push(Math.random().toString(16).substr(2, 7))
+}
+
 const push = () => {
-  remote.value.push(...local.value.slice(remote.value.length))
-  hasRemote.value = false
+  remote.value = [...local.value]
 }
+
 const pull = () => {
-  if (hasRemote.value) local.value.push(Math.random().toString(16).substr(2, 7))
-  hasRemote.value = false
+  local.value = [...remote.value]
 }
+
+const ahead = computed(() =>
+  Math.max(0, local.value.length - remote.value.length)
+)
+const behind = computed(() =>
+  Math.max(0, remote.value.length - local.value.length)
+)
+
 const reset = () => {
   local.value = []
   remote.value = []
-  hasRemote.value = false
 }
 </script>
 
@@ -98,6 +120,26 @@ const reset = () => {
   font-weight: 600;
   margin-bottom: 0.5rem;
 }
+.meta {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+.badge {
+  padding: 0.2rem 0.6rem;
+  border-radius: 999px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-2);
+  font-size: 0.75rem;
+  font-family: var(--vp-font-family-mono);
+}
+.hint {
+  color: var(--vp-c-text-3);
+  font-size: 0.75rem;
+}
 .commits {
   min-height: 80px;
 }
@@ -113,13 +155,13 @@ const reset = () => {
   border-radius: 50%;
 }
 .dot.local {
-  background: #3b82f6;
+  background: var(--vp-c-brand);
 }
 .dot.remote {
-  background: #10b981;
+  background: rgba(var(--vp-c-brand-rgb), 0.5);
 }
 .hash {
-  font-family: monospace;
+  font-family: var(--vp-font-family-mono);
   font-size: 0.875rem;
   color: var(--vp-c-text-2);
 }
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitScenariosDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitScenariosDemo.vue
new file mode 100644
index 0000000..f7f3b0f
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitScenariosDemo.vue
@@ -0,0 +1,524 @@
+<template>
+  <div class="git-scenarios-demo">
+    <div class="header">
+      <div class="title">
+        <div class="h">常见场景：直接照抄的 Git 命令</div>
+        <div class="sub">
+          选一个场景，按步骤执行；每一步都解释“为什么这么做”。
+        </div>
+      </div>
+
+      <div class="actions">
+        <button class="btn" @click="prevStep" :disabled="activeStepIndex === 0">
+          上一步
+        </button>
+        <button
+          class="btn primary"
+          @click="nextStep"
+          :disabled="activeStepIndex >= activeScenario.steps.length - 1"
+        >
+          下一步
+        </button>
+        <button class="btn" @click="resetSteps">重置</button>
+      </div>
+    </div>
+
+    <div class="tabs">
+      <button
+        v-for="s in scenarios"
+        :key="s.id"
+        class="tab"
+        :class="{ active: activeScenarioId === s.id }"
+        @click="selectScenario(s.id)"
+      >
+        {{ s.title }}
+        <span class="tag">{{ s.level }}</span>
+      </button>
+    </div>
+
+    <div class="content">
+      <div class="scenario-meta">
+        <div class="scenario-desc">{{ activeScenario.desc }}</div>
+        <div class="scenario-note" v-if="activeScenario.note">
+          {{ activeScenario.note }}
+        </div>
+      </div>
+
+      <div class="step-card">
+        <div class="step-top">
+          <div class="step-title">
+            Step {{ activeStepIndex + 1 }} / {{ activeScenario.steps.length }}
+            <span class="step-name">{{ activeStep.title }}</span>
+          </div>
+          <button class="copy-btn" @click="copy(activeStep.cmd)">
+            {{ copied ? '已复制' : '复制命令' }}
+          </button>
+        </div>
+
+        <div class="cmd">
+          <code>{{ activeStep.cmd }}</code>
+        </div>
+
+        <div v-if="activeStep.output" class="output">
+          <div class="label">你通常会看到：</div>
+          <pre><code>{{ activeStep.output }}</code></pre>
+        </div>
+
+        <div class="why">
+          <div class="label">为什么：</div>
+          <div class="text">{{ activeStep.why }}</div>
+        </div>
+
+        <div v-if="activeStep.warn" class="warn">
+          <div class="label">注意：</div>
+          <div class="text">{{ activeStep.warn }}</div>
+        </div>
+      </div>
+
+      <div class="tips">
+        <div class="tips-title">最容易踩坑的 3 件事</div>
+        <ul>
+          <li>
+            <strong>先看状态再动手：</strong>每次操作前先跑一次
+            <code>git status</code>。
+          </li>
+          <li>
+            <strong>只提交“你想提交的东西”：</strong>用
+            <code>git add path</code> 精准暂存，别习惯性
+            <code>git add .</code>。
+          </li>
+          <li>
+            <strong>撤销要分层：</strong>没进暂存 / 进了暂存 / 已经
+            commit，命令完全不同。
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, ref } from 'vue'
+
+const scenarios = [
+  {
+    id: 'daily',
+    title: '日常提交',
+    level: '必会',
+    desc: '在本地改代码并提交；这是你 90% 的 Git 使用场景。',
+    steps: [
+      {
+        title: '看当前状态',
+        cmd: 'git status',
+        output:
+          'On branch main\nChanges not staged for commit:\n  modified:   src/app.js',
+        why: '先确认“你在哪个分支 + 改了哪些文件”，避免在错误分支提交。'
+      },
+      {
+        title: '暂存你要提交的文件',
+        cmd: 'git add src/app.js',
+        output:
+          'On branch main\nChanges to be committed:\n  modified:   src/app.js',
+        why: '把“这次提交要包含的改动”放进暂存区，确保提交内容可控。'
+      },
+      {
+        title: '提交并写清楚信息',
+        cmd: 'git commit -m \"fix: handle empty input\"',
+        output:
+          '[main 1a2b3c4] fix: handle empty input\n 1 file changed, 3 insertions(+)',
+        why: 'commit message 要能让未来的你/同事一眼看懂“改了什么 + 为什么”。'
+      }
+    ]
+  },
+  {
+    id: 'new-project',
+    title: '新项目推远程',
+    level: '常用',
+    desc: '把本地新项目推到 GitHub/GitLab（remote 一般叫 origin）。',
+    note: '前提：你已经在远端创建了空仓库（不要勾选 README/License，以免产生冲突）。',
+    steps: [
+      {
+        title: '初始化仓库',
+        cmd: 'git init',
+        output: 'Initialized empty Git repository in .../.git/',
+        why: '让当前目录变成一个 Git 仓库。'
+      },
+      {
+        title: '第一次提交',
+        cmd: 'git add . && git commit -m \"chore: initial commit\"',
+        output: '[main ...] chore: initial commit',
+        why: '没有提交就无法 push；先把“初始状态”存档。'
+      },
+      {
+        title: '绑定远程地址',
+        cmd: 'git remote add origin <REMOTE_URL>',
+        output: '',
+        why: '告诉 Git 你的云端仓库在哪里（origin 只是一个名字）。'
+      },
+      {
+        title: '推送并建立追踪关系',
+        cmd: 'git push -u origin main',
+        output: 'Branch \"main\" set up to track \"origin/main\".',
+        why: '加 -u 后，以后可以直接用 git push / git pull。'
+      }
+    ]
+  },
+  {
+    id: 'branch-pr',
+    title: '开分支做功能',
+    level: '必会',
+    desc: '在 feature 分支开发，推送后提 PR；这是团队协作的基本功。',
+    steps: [
+      {
+        title: '更新主分支',
+        cmd: 'git switch main && git pull',
+        output: '',
+        why: '在开新分支前先把 main 更新到最新，减少未来合并冲突。'
+      },
+      {
+        title: '创建并切到 feature 分支',
+        cmd: 'git switch -c feat/login-form',
+        output: "Switched to a new branch 'feat/login-form'",
+        why: '把改动隔离在分支里，主分支保持可随时发布。'
+      },
+      {
+        title: '提交并推送分支',
+        cmd: 'git push -u origin feat/login-form',
+        output: '',
+        why: '推到远端后，才能在 GitHub/GitLab 上发起 PR/MR。'
+      }
+    ]
+  },
+  {
+    id: 'undo',
+    title: '撤销/回滚',
+    level: '救命',
+    desc: '写错了别慌：先判断“改动在哪一层”。',
+    steps: [
+      {
+        title: '未 add：丢掉工作区改动',
+        cmd: 'git restore <file>',
+        output: '',
+        why: '只撤销工作区的修改，不影响暂存区和提交历史。',
+        warn: '会丢弃未提交的改动；不确定时先备份或用 stash。'
+      },
+      {
+        title: '已 add：撤回暂存',
+        cmd: 'git restore --staged <file>',
+        output: '',
+        why: '把文件从暂存区撤回到工作区，便于重新选择提交内容。'
+      },
+      {
+        title: '已 commit：推荐用 revert',
+        cmd: 'git revert <commit>',
+        output: '',
+        why: 'revert 会生成一个“反向提交”，对协作更安全（不会改写历史）。',
+        warn: '不要在共享分支随意 reset --hard（会让别人同步困难）。'
+      }
+    ]
+  },
+  {
+    id: 'conflict',
+    title: '解决冲突',
+    level: '常见',
+    desc: '多人改同一段代码时，Git 需要你手动选择。',
+    steps: [
+      {
+        title: '合并/拉取触发冲突',
+        cmd: 'git merge <branch>',
+        output: 'CONFLICT (content): Merge conflict in src/app.js',
+        why: 'Git 无法自动决定保留哪一边的改动。'
+      },
+      {
+        title: '打开冲突文件并解决标记',
+        cmd: 'git status',
+        output:
+          'Unmerged paths:\n  both modified:   src/app.js\n\nfix conflicts and run \"git commit\"',
+        why: '用 status 定位冲突文件，然后打开文件删掉 <<<<<<</=======/>>>>>>> 标记。'
+      },
+      {
+        title: '标记冲突已解决并提交',
+        cmd: 'git add src/app.js && git commit',
+        output: '',
+        why: 'add 表示“我已解决冲突”；commit 记录一次合并结果。'
+      }
+    ]
+  }
+]
+
+const activeScenarioId = ref(scenarios[0].id)
+const activeStepIndex = ref(0)
+const copied = ref(false)
+
+const activeScenario = computed(
+  () => scenarios.find((s) => s.id === activeScenarioId.value) || scenarios[0]
+)
+
+const activeStep = computed(
+  () => activeScenario.value.steps[activeStepIndex.value]
+)
+
+const resetSteps = () => {
+  activeStepIndex.value = 0
+}
+
+const selectScenario = (id) => {
+  activeScenarioId.value = id
+  resetSteps()
+}
+
+const nextStep = () => {
+  activeStepIndex.value = Math.min(
+    activeScenario.value.steps.length - 1,
+    activeStepIndex.value + 1
+  )
+}
+
+const prevStep = () => {
+  activeStepIndex.value = Math.max(0, activeStepIndex.value - 1)
+}
+
+const copy = async (text) => {
+  try {
+    await navigator.clipboard.writeText(text)
+    copied.value = true
+    setTimeout(() => {
+      copied.value = false
+    }, 800)
+  } catch {
+    copied.value = false
+  }
+}
+</script>
+
+<style scoped>
+.git-scenarios-demo {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+  padding: 1.25rem;
+  margin: 1rem 0;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 0.75rem;
+}
+
+.title .h {
+  font-weight: 700;
+  font-size: 1rem;
+  color: var(--vp-c-text-1);
+}
+
+.title .sub {
+  margin-top: 0.25rem;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+}
+
+.actions {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+.btn {
+  padding: 0.45rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.btn.primary {
+  background: var(--vp-c-brand);
+  border-color: var(--vp-c-brand);
+  color: var(--vp-c-bg);
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.tabs {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0.75rem 0 1rem;
+}
+
+.tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: 999px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.tab.active {
+  border-color: rgba(var(--vp-c-brand-rgb), 0.35);
+  box-shadow: 0 0 0 3px rgba(var(--vp-c-brand-rgb), 0.12);
+}
+
+.tag {
+  font-size: 0.75rem;
+  padding: 0.15rem 0.5rem;
+  border-radius: 999px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-2);
+}
+
+.scenario-meta {
+  margin-bottom: 0.75rem;
+}
+
+.scenario-desc {
+  color: var(--vp-c-text-1);
+  line-height: 1.6;
+}
+
+.scenario-note {
+  margin-top: 0.5rem;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+}
+
+.step-card {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 1rem;
+}
+
+.step-top {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.step-title {
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+}
+
+.step-name {
+  margin-left: 0.5rem;
+  font-weight: 600;
+  color: var(--vp-c-text-2);
+}
+
+.copy-btn {
+  padding: 0.35rem 0.65rem;
+  border-radius: 6px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.cmd {
+  font-family: var(--vp-font-family-mono);
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  padding: 0.75rem;
+  overflow-x: auto;
+}
+
+.cmd code {
+  font-size: 0.9rem;
+}
+
+.label {
+  font-size: 0.875rem;
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.35rem;
+}
+
+.output {
+  margin-top: 0.75rem;
+}
+
+.output pre {
+  margin: 0;
+  padding: 0.75rem;
+  border-radius: 6px;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  overflow-x: auto;
+}
+
+.why,
+.warn {
+  margin-top: 0.75rem;
+}
+
+.why .text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+.warn {
+  padding: 0.75rem;
+  border-radius: 6px;
+  border: 1px solid rgba(var(--vp-c-brand-rgb), 0.18);
+  background: rgba(var(--vp-c-brand-rgb), 0.06);
+}
+
+.warn .text {
+  color: var(--vp-c-text-2);
+  line-height: 1.7;
+}
+
+.tips {
+  margin-top: 1rem;
+  padding: 1rem;
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+}
+
+.tips-title {
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.5rem;
+}
+
+.tips ul {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--vp-c-text-2);
+}
+
+@media (max-width: 720px) {
+  .header {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  .actions {
+    justify-content: flex-start;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitThreeAreasDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitThreeAreasDemo.vue
index 68acb01..f97b8fe 100644
--- a/docs/.vitepress/theme/components/appendix/git-intro/GitThreeAreasDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitThreeAreasDemo.vue
@@ -121,11 +121,22 @@
         </div>
       </div>
     </div>
+
+    <div class="bottom">
+      <div class="block">
+        <div class="block-title">当前等价命令</div>
+        <pre class="mono"><code>{{ historyText }}</code></pre>
+      </div>
+      <div class="block">
+        <div class="block-title">git status（模拟）</div>
+        <pre class="mono"><code>{{ statusText }}</code></pre>
+      </div>
+    </div>
   </div>
 </template>
 
 <script setup>
-import { ref } from 'vue'
+import { ref, computed } from 'vue'
 
 const fileIdCounter = ref(1)
 
@@ -139,6 +150,32 @@ const workingFiles = ref([
 
 const stagedFiles = ref([])
 const commits = ref([])
+const history = ref(['$ git status'])
+
+const pushHistory = (line) => {
+  history.value.push(line)
+  if (history.value.length > 6)
+    history.value.splice(0, history.value.length - 6)
+}
+
+const historyText = computed(() => history.value.join('\n'))
+
+const statusText = computed(() => {
+  const lines = ['On branch main']
+  if (stagedFiles.value.length === 0 && workingFiles.value.length === 0) {
+    lines.push('nothing to commit, working tree clean')
+    return lines.join('\n')
+  }
+  if (stagedFiles.value.length) {
+    lines.push('Changes to be committed:')
+    stagedFiles.value.forEach((f) => lines.push(`  new file:   ${f.name}`))
+  }
+  if (workingFiles.value.length) {
+    lines.push('Untracked files:')
+    workingFiles.value.forEach((f) => lines.push(`  ${f.name}`))
+  }
+  return lines.join('\n')
+})
 
 const createNewFile = () => {
   const types = [
@@ -152,6 +189,7 @@ const createNewFile = () => {
     name: randomType.name,
     icon: randomType.icon
   })
+  pushHistory(`$ touch ${randomType.name}`)
 }
 
 const addToStaging = (file) => {
@@ -159,6 +197,7 @@ const addToStaging = (file) => {
   if (index !== -1) {
     workingFiles.value.splice(index, 1)
     stagedFiles.value.push(file)
+    pushHistory(`$ git add ${file.name}`)
   }
 }
 
@@ -167,6 +206,7 @@ const unstageFile = (file) => {
   if (index !== -1) {
     stagedFiles.value.splice(index, 1)
     workingFiles.value.push(file)
+    pushHistory(`$ git restore --staged ${file.name}`)
   }
 }
 
@@ -190,14 +230,16 @@ const commitFiles = () => {
     message: randomMsg,
     files: files.map((f) => f.name)
   })
+
+  pushHistory(`$ git commit -m "${randomMsg}"`)
 }
 </script>
 
 <style scoped>
 .three-areas-demo {
   border: 1px solid var(--vp-c-divider);
-  border-radius: 12px;
-  background-color: var(--vp-c-bg-alt);
+  border-radius: 8px;
+  background-color: var(--vp-c-bg-soft);
   padding: 1rem;
   margin: 1rem 0;
   font-family: var(--vp-font-family-mono);
@@ -215,12 +257,11 @@ const commitFiles = () => {
 .zone {
   flex: 1;
   background: var(--vp-c-bg);
-  border-radius: 12px;
+  border-radius: 8px;
   padding: 12px;
-  border: 2px solid transparent;
+  border: 1px solid var(--vp-c-divider);
   display: flex;
   flex-direction: column;
-  transition: all 0.3s ease;
   min-height: 300px;
 }
 
@@ -262,8 +303,7 @@ const commitFiles = () => {
 
 /* 1. Working Desk */
 .zone.working {
-  border-color: #f59e0b;
-  background: #fffbeb;
+  border-color: rgba(var(--vp-c-brand-rgb), 0.25);
 }
 .desk-surface {
   flex: 1;
@@ -272,14 +312,15 @@ const commitFiles = () => {
   align-content: flex-start;
   gap: 8px;
   padding: 8px;
-  background-image: radial-gradient(#e5e7eb 1px, transparent 1px);
+  background: var(--vp-c-bg-soft);
   background-size: 10px 10px;
   border-radius: 8px;
+  border: 1px dashed var(--vp-c-divider);
 }
 
 .file-card {
-  background: white;
-  border: 1px solid #d1d5db;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
   border-radius: 6px;
   padding: 8px;
   width: 80px;
@@ -289,15 +330,12 @@ const commitFiles = () => {
   align-items: center;
   justify-content: center;
   cursor: pointer;
-  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
   transition: all 0.2s;
   position: relative;
 }
 
 .file-card:hover {
-  transform: translateY(-4px) rotate(2deg);
-  box-shadow: 0 8px 12px rgba(0, 0, 0, 0.1);
-  border-color: #f59e0b;
+  border-color: var(--vp-c-brand);
 }
 
 .file-icon {
@@ -316,8 +354,8 @@ const commitFiles = () => {
   left: 0;
   right: 0;
   bottom: 0;
-  background: rgba(245, 158, 11, 0.9);
-  color: white;
+  background: rgba(var(--vp-c-brand-rgb), 0.9);
+  color: var(--vp-c-bg);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -332,8 +370,8 @@ const commitFiles = () => {
 }
 
 .create-btn {
-  background: #f59e0b;
-  color: white;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
   border: none;
   padding: 4px 12px;
   border-radius: 12px;
@@ -344,8 +382,7 @@ const commitFiles = () => {
 
 /* 2. Staging Box */
 .zone.staging {
-  border-color: #3b82f6;
-  background: #eff6ff;
+  border-color: rgba(var(--vp-c-brand-rgb), 0.25);
 }
 .box-container {
   flex: 1;
@@ -360,8 +397,8 @@ const commitFiles = () => {
 .box-body {
   width: 100%;
   height: 140px;
-  background: #dbeafe;
-  border: 2px solid #3b82f6;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
   border-top: none;
   border-radius: 0 0 8px 8px;
   position: relative;
@@ -389,10 +426,10 @@ const commitFiles = () => {
   font-size: 0.8rem;
 }
 .file-card.mini:hover {
-  border-color: #ef4444;
+  border-color: var(--vp-c-brand);
 }
 .file-card.mini .action-hint {
-  background: rgba(239, 68, 68, 0.9);
+  background: rgba(var(--vp-c-brand-rgb), 0.9);
 }
 
 .box-flap {
@@ -400,8 +437,8 @@ const commitFiles = () => {
   top: -20px;
   width: 45%;
   height: 20px;
-  background: #93c5fd;
-  border: 2px solid #3b82f6;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
   border-bottom: none;
   transition: all 0.5s;
 }
@@ -423,30 +460,27 @@ const commitFiles = () => {
   text-align: center;
 }
 .commit-btn {
-  background: #3b82f6;
-  color: white;
+  background: var(--vp-c-brand);
+  color: var(--vp-c-bg);
   border: none;
   padding: 8px 16px;
   border-radius: 20px;
   font-weight: bold;
   cursor: pointer;
   transition: all 0.2s;
-  box-shadow: 0 4px 6px rgba(59, 130, 246, 0.3);
 }
 .commit-btn:disabled {
-  background: #93c5fd;
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-2);
   cursor: not-allowed;
-  box-shadow: none;
 }
 .commit-btn:hover:not(:disabled) {
-  transform: translateY(-2px);
-  box-shadow: 0 6px 8px rgba(59, 130, 246, 0.4);
+  opacity: 0.95;
 }
 
 /* 3. Repo Cabinet */
 .zone.repo {
-  border-color: #10b981;
-  background: #ecfdf5;
+  border-color: rgba(var(--vp-c-brand-rgb), 0.25);
 }
 .cabinet-body {
   flex: 1;
@@ -457,22 +491,21 @@ const commitFiles = () => {
 }
 
 .drawer-item {
-  background: white;
-  border: 1px solid #10b981;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
   border-radius: 4px;
   height: 50px;
   display: flex;
   align-items: center;
   padding: 0 12px;
   gap: 12px;
-  box-shadow: 0 2px 0 #059669; /* 3D effect */
   position: relative;
 }
 .drawer-handle {
   width: 30px;
   height: 6px;
-  background: #d1fae5;
-  border: 1px solid #10b981;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
   border-radius: 2px;
 }
 .commit-info {
@@ -482,8 +515,8 @@ const commitFiles = () => {
 }
 .commit-hash {
   font-size: 0.6rem;
-  color: #10b981;
-  font-family: monospace;
+  color: var(--vp-c-text-2);
+  font-family: var(--vp-font-family-mono);
 }
 .commit-msg {
   font-size: 0.8rem;
@@ -521,6 +554,38 @@ const commitFiles = () => {
   font-size: 0.8rem;
 }
 
+.bottom {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.75rem;
+  margin-top: 1rem;
+}
+
+.block {
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 0.75rem;
+  min-width: 260px;
+}
+
+.block-title {
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin-bottom: 0.5rem;
+}
+
+.mono {
+  margin: 0;
+  padding: 0.75rem;
+  background: var(--vp-c-bg-alt);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+  font-size: 0.8rem;
+}
+
 /* Transitions */
 .file-pop-enter-active,
 .file-pop-leave-active {
@@ -571,5 +636,9 @@ const commitFiles = () => {
     width: 2px;
     height: 20px;
   }
+
+  .bottom {
+    grid-template-columns: 1fr;
+  }
 }
 </style>
diff --git a/docs/.vitepress/theme/components/appendix/git-intro/GitWorkflowDemo.vue b/docs/.vitepress/theme/components/appendix/git-intro/GitWorkflowDemo.vue
index 11d37f1..6785e5c 100644
--- a/docs/.vitepress/theme/components/appendix/git-intro/GitWorkflowDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/git-intro/GitWorkflowDemo.vue
@@ -9,25 +9,36 @@
   <div class="git-workflow-demo">
     <!-- 控制面板 -->
     <div class="control-panel">
-      <button @click="initRepo" :disabled="inited" class="action-btn">
+      <button
+        @click="initRepo"
+        :disabled="inited || mergePending"
+        class="action-btn"
+      >
         🎯 初始化仓库
       </button>
-      <button @click="makeCommit" :disabled="!inited" class="action-btn">
+      <button
+        @click="makeCommit"
+        :disabled="!inited || mergePending"
+        class="action-btn"
+      >
         ✅ 提交
       </button>
       <button
         @click="createBranch"
-        :disabled="!inited || hasBranch"
+        :disabled="!inited || hasBranch || mergePending"
         class="action-btn"
       >
         🌿 创建分支
       </button>
       <button
-        @click="mergeBranch"
-        :disabled="!hasBranch || merging"
+        @click="prepareMerge"
+        :disabled="!hasBranch || mergePending"
         class="action-btn"
       >
-        🔀 合并分支
+        🔀 准备合并
+      </button>
+      <button @click="finishMerge" :disabled="!mergePending" class="action-btn">
+        ✅ 完成合并
       </button>
       <button @click="reset" class="action-btn secondary">🔄 重置</button>
     </div>
@@ -68,10 +79,10 @@
 
           <!-- 合并线 -->
           <path
-            v-if="merging"
+            v-if="mergePending"
             d="M 300 100 Q 320 80, 320 60"
             fill="none"
-            stroke="#f59e0b"
+            stroke="var(--vp-c-brand)"
             stroke-width="2"
             stroke-dasharray="5,5"
           />
@@ -127,12 +138,12 @@ import { ref, computed } from 'vue'
 
 const inited = ref(false)
 const hasBranch = ref(false)
-const merging = ref(false)
+const mergePending = ref(false)
 const mainCommits = ref([])
 const branchCommits = ref([])
 
 const status = computed(() => {
-  if (merging) return '合并中...'
+  if (mergePending.value) return '准备合并：检查改动/解决冲突后再完成合并'
   if (hasBranch) return '分支已创建'
   if (inited) return '已初始化'
   return '未初始化'
@@ -156,22 +167,23 @@ const createBranch = () => {
   }
 }
 
-const mergeBranch = () => {
-  if (hasBranch.value) {
-    merging.value = true
-    setTimeout(() => {
-      mainCommits.value.push({ hash: Math.random().toString(16).substr(2, 6) })
-      hasBranch.value = false
-      branchCommits.value = []
-      merging.value = false
-    }, 1000)
-  }
+const prepareMerge = () => {
+  if (!hasBranch.value) return
+  mergePending.value = true
+}
+
+const finishMerge = () => {
+  if (!mergePending.value) return
+  mainCommits.value.push({ hash: Math.random().toString(16).substr(2, 6) })
+  hasBranch.value = false
+  branchCommits.value = []
+  mergePending.value = false
 }
 
 const reset = () => {
   inited.value = false
   hasBranch.value = false
-  merging.value = false
+  mergePending.value = false
   mainCommits.value = []
   branchCommits.value = []
 }
diff --git a/docs/.vitepress/theme/components/appendix/queue-design/PeakShavingDemo.vue b/docs/.vitepress/theme/components/appendix/queue-design/PeakShavingDemo.vue
index 4996893..4578549 100644
--- a/docs/.vitepress/theme/components/appendix/queue-design/PeakShavingDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/queue-design/PeakShavingDemo.vue
@@ -6,131 +6,102 @@
   <div class="peak-shaving-demo">
     <div class="header">
       <div class="title">削峰填谷：把高峰"摊平"</div>
-      <div class="subtitle">调整请求速率，观察队列如何缓冲流量</div>
+      <div class="subtitle">模拟流量突增场景，观察队列如何保护后端系统</div>
     </div>
 
-    <div class="controls">
-      <div class="control">
-        <label>
-          请求速率：<strong>{{ requestRate }}</strong> 请求/秒
-        </label>
-        <input
-          v-model="requestRate"
-          type="range"
-          min="100"
-          max="10000"
-          step="100"
-        />
-      </div>
-      <div class="control">
-        <label>
-          处理速率：<strong>{{ processRate }}</strong> 请求/秒
-        </label>
-        <input
-          v-model="processRate"
-          type="range"
-          min="50"
-          max="500"
-          step="10"
-        />
-      </div>
-      <div class="control">
-        <label>
-          队列容量：<strong>{{ queueCapacity }}</strong>
-        </label>
-        <input
-          v-model="queueCapacity"
-          type="range"
-          min="100"
-          max="5000"
-          step="100"
-        />
-      </div>
-    </div>
-
-    <div class="simulation">
-      <button class="sim-btn" @click="toggleSimulation">
-        {{ running ? '⏸️ 暂停' : '▶️ 开始模拟' }}
-      </button>
-      <button class="sim-btn reset" @click="reset">🔄 重置</button>
-    </div>
-
-    <div class="flow-visualization">
-      <div class="column incoming">
-        <div class="col-header">📥 入站流量</div>
-        <div class="rate-display">{{ requestRate }}/s</div>
-        <div class="bar-container">
-          <div class="bar-fill" :style="{ height: requestHeight + '%' }"></div>
+    <div class="main-layout">
+      <!-- 左侧：控制面板 -->
+      <div class="controls-panel">
+        <div class="control-group">
+          <div class="label-row">
+            <span class="label">处理能力 (Consumer)</span>
+            <span class="value">{{ processRate }} req/s</span>
+          </div>
+          <input
+            v-model="processRate"
+            type="range"
+            min="50"
+            max="1000"
+            step="50"
+            class="range-input process-range"
+          />
+          <div class="desc">后端系统的最大处理速度</div>
         </div>
-        <div class="particles incoming-particles">
-          <div
-            v-for="p in incomingParticles"
-            :key="p.id"
-            class="particle"
-            :style="{ animationDelay: p.delay + 'ms' }"
-          ></div>
+
+        <div class="control-group">
+          <div class="label-row">
+            <span class="label">队列容量 (Queue Size)</span>
+            <span class="value">{{ queueCapacity }}</span>
+          </div>
+          <input
+            v-model="queueCapacity"
+            type="range"
+            min="500"
+            max="10000"
+            step="500"
+            class="range-input queue-range"
+          />
+          <div class="desc">消息队列能暂存的最大请求数</div>
+        </div>
+
+        <div class="actions">
+          <button 
+            class="action-btn burst-btn" 
+            @click="triggerBurst" 
+            :disabled="isBursting"
+          >
+            ⚡️ 模拟秒杀流量突增
+          </button>
+          <button class="action-btn reset-btn" @click="reset">
+            🔄 重置系统
+          </button>
         </div>
       </div>
 
-      <div class="column queue">
-        <div class="col-header">📦 消息队列</div>
-        <div class="queue-info">
-          <div class="queue-count">{{ queueLength }} / {{ queueCapacity }}</div>
-          <div class="queue-percent">{{ queuePercent }}%</div>
+      <!-- 右侧：实时监控 -->
+      <div class="monitor-panel">
+        <!-- 状态指标卡片 -->
+        <div class="metrics-grid">
+          <div class="metric-item">
+            <div class="m-label">当前入站流量</div>
+            <div class="m-value blue">{{ currentRequestRate }} <span class="unit">req/s</span></div>
+          </div>
+          <div class="metric-item">
+            <div class="m-label">队列积压量</div>
+            <div class="m-value orange">{{ queueLength }} <span class="unit">msgs</span></div>
+            <div class="m-bar-bg">
+              <div class="m-bar-fill" :style="{ width: queuePercent + '%', background: queueColor }"></div>
+            </div>
+          </div>
+          <div class="metric-item">
+            <div class="m-label">实际处理速率</div>
+            <div class="m-value green">{{ currentProcessRate }} <span class="unit">req/s</span></div>
+          </div>
+          <div class="metric-item">
+            <div class="m-label">丢弃请求 (限流)</div>
+            <div class="m-value red">{{ rejectedCount }} <span class="unit">req</span></div>
+          </div>
         </div>
-        <div class="queue-bar-container">
-          <div
-            class="queue-bar"
-            :class="queueStatus"
-            :style="{ width: queuePercent + '%' }"
-          ></div>
-        </div>
-        <div class="queue-status-text">{{ queueStatusText }}</div>
-      </div>
 
-      <div class="column outgoing">
-        <div class="col-header">📤 处理流量</div>
-        <div class="rate-display">{{ processRate }}/s</div>
-        <div class="bar-container">
-          <div
-            class="bar-fill stable"
-            :style="{ height: processHeight + '%' }"
-          ></div>
+        <!-- 实时图表 -->
+        <div class="chart-container">
+          <canvas ref="chartCanvas" width="600" height="200"></canvas>
+          <div class="chart-legend">
+            <span class="legend-item"><span class="dot blue"></span>入站流量 (用户请求)</span>
+            <span class="legend-item"><span class="dot green"></span>处理流量 (系统负载)</span>
+            <span class="legend-item"><span class="dot orange"></span>队列积压</span>
+          </div>
         </div>
-        <div class="particles outgoing-particles">
-          <div
-            v-for="p in outgoingParticles"
-            :key="p.id"
-            class="particle processed"
-            :style="{ animationDelay: p.delay + 'ms' }"
-          ></div>
-        </div>
-      </div>
-    </div>
-
-    <div class="metrics">
-      <div class="metric-card">
-        <div class="metric-label">队列积压</div>
-        <div class="metric-value">{{ queueLength }}</div>
-      </div>
-      <div class="metric-card">
-        <div class="metric-label">平均等待时间</div>
-        <div class="metric-value">{{ avgWaitTime }}s</div>
-      </div>
-      <div class="metric-card">
-        <div class="metric-label">已处理请求</div>
-        <div class="metric-value">{{ processedCount }}</div>
-      </div>
-      <div class="metric-card">
-        <div class="metric-label">拒绝请求</div>
-        <div class="metric-value error">{{ rejectedCount }}</div>
       </div>
     </div>
 
     <div class="scenario-tips">
-      <div class="tip">
-        <strong>💡 典型场景：</strong>秒杀活动 1 秒内 10 万请求，数据库只能处理
-        1000/秒
+      <div class="tip-icon">💡</div>
+      <div class="tip-content">
+        <strong>核心原理：</strong>
+        当<strong>入站流量</strong>（蓝色）超过<strong>处理能力</strong>（绿色直线）时，多余的请求会被存入<strong>消息队列</strong>（橙色区域）。
+        <br/>
+        一旦流量高峰过去，系统会继续全速处理队列中的积压，直到队列清空。这就是"削峰填谷"。
       </div>
     </div>
   </div>
@@ -139,126 +110,220 @@
 <script setup>
 import { ref, computed, onMounted, onUnmounted } from 'vue'
 
-const requestRate = ref(5000)
-const processRate = ref(200)
-const queueCapacity = ref(2000)
-const queueLength = ref(0)
-const processedCount = ref(0)
-const rejectedCount = ref(0)
-const running = ref(false)
+// 核心状态
+const processRate = ref(200)      // 消费速率 (req/s)
+const queueCapacity = ref(2000)   // 队列容量
+const queueLength = ref(0)        // 当前队列长度
+const rejectedCount = ref(0)      // 总丢弃数
 
-let interval = null
-let particleId = 0
+// 实时状态（用于展示和图表）
+const currentRequestRate = ref(100) // 当前产生的请求速率
+const currentProcessRate = ref(0)   // 当前实际处理的速率
+const isBursting = ref(false)
 
-const incomingParticles = ref([])
-const outgoingParticles = ref([])
+// 图表相关
+const chartCanvas = ref(null)
+let ctx = null
+let animationFrameId = null
+const historyLength = 300 // 记录最近 N 帧
+const dataHistory = [] // { input, process, queue }
 
-const requestHeight = computed(() =>
-  Math.min(100, (requestRate.value / 10000) * 100)
-)
-const processHeight = computed(() =>
-  Math.min(100, (processRate.value / 500) * 100)
-)
-const queuePercent = computed(() =>
-  Math.round((queueLength.value / queueCapacity.value) * 100)
-)
+// 模拟循环
+let lastTime = Date.now()
+const updateLoop = () => {
+  const now = Date.now()
+  const dt = (now - lastTime) / 1000 // delta time in seconds
+  lastTime = now
 
-const queueStatus = computed(() => {
-  if (queuePercent.value >= 90) return 'critical'
-  if (queuePercent.value >= 70) return 'warning'
-  return 'normal'
-})
+  // 1. 生成流量 (模拟波动的入站流量)
+  // 如果在突发模式下，流量激增；否则维持在低水位波动
+  let targetInput = isBursting.value ? 2000 : 100 + Math.random() * 50
+  
+  // 平滑过渡入站流量
+  const smoothing = 0.1
+  currentRequestRate.value = Math.round(
+    currentRequestRate.value * (1 - smoothing) + targetInput * smoothing
+  )
 
-const queueStatusText = computed(() => {
-  if (queuePercent.value >= 90) return '⚠️ 队列接近满载'
-  if (queuePercent.value >= 70) return '⚡ 队列积压较多'
-  return '✅ 队列状态良好'
-})
+  // 2. 计算本帧新增请求
+  const newRequests = Math.round(currentRequestRate.value * dt * 10) // 放大系数以便观察
+  
+  // 3. 入队逻辑
+  const availableSpace = queueCapacity.value - queueLength.value
+  const accepted = Math.min(newRequests, availableSpace)
+  const rejected = newRequests - accepted
+  
+  queueLength.value += accepted
+  rejectedCount.value += rejected
 
-const avgWaitTime = computed(() => {
-  if (processRate.value === 0) return '∞'
-  return (queueLength.value / processRate.value).toFixed(1)
-})
+  // 4. 处理逻辑 (出队)
+  // 实际处理速率取决于：队列里有多少货，以及处理能力上限
+  // 如果队列足够多，就满负荷处理；否则只处理队列里有的
+  const maxProcessable = Math.round(processRate.value * dt * 10)
+  const processed = Math.min(queueLength.value, maxProcessable)
+  
+  queueLength.value -= processed
+  
+  // 计算瞬时处理速率 (用于显示)
+  currentProcessRate.value = Math.round(processed / (dt * 10))
 
-const toggleSimulation = () => {
-  running.value = !running.value
-  if (running.value) {
-    startSimulation()
-  } else {
-    stopSimulation()
+  // 5. 记录历史数据用于绘图
+  dataHistory.push({
+    input: currentRequestRate.value,
+    process: currentProcessRate.value,
+    queue: queueLength.value,
+    maxQueue: queueCapacity.value
+  })
+
+  if (dataHistory.length > historyLength) {
+    dataHistory.shift()
   }
+
+  drawChart()
+  animationFrameId = requestAnimationFrame(updateLoop)
 }
 
-const startSimulation = () => {
-  interval = setInterval(() => {
-    // 模拟请求到达
-    const requests = Math.floor(requestRate.value / 10)
+// 绘图逻辑
+const drawChart = () => {
+  if (!ctx || !chartCanvas.value) return
+  
+  // 动态调整画布大小以匹配显示尺寸（解决模糊和拉伸问题）
+  const canvas = chartCanvas.value
+  const dpr = window.devicePixelRatio || 1
+  const rect = canvas.getBoundingClientRect()
+  
+  // 只有当尺寸变化时才重置 canvas 尺寸
+  if (canvas.width !== rect.width * dpr || canvas.height !== rect.height * dpr) {
+    canvas.width = rect.width * dpr
+    canvas.height = rect.height * dpr
+    // 缩放上下文以适配 DPR
+    ctx.scale(dpr, dpr)
+  }
 
-    // 尝试加入队列
-    const available = queueCapacity.value - queueLength.value
-    const accepted = Math.min(requests, available)
-    const rejected = requests - accepted
+  // 逻辑宽高（CSS像素）
+  const width = rect.width
+  const height = rect.height
+  
+  // 必须清除整个物理画布区域
+  ctx.clearRect(0, 0, width, height) // 由于 scale 了，这里用逻辑宽高即可吗？
+  // 不，clearRect 受 scale 影响。所以 clearRect(0,0, width, height) 是对的。
+  // 但是为了安全，通常建议用 save/restore 或者直接重置 transform 清除。
+  // 简单起见，我们假设 ctx.scale 已经生效。
+  
+  // 实际上，最好是在 resize 时只设置一次 scale。
+  // 让我们简化一下：每帧都重置 transform 并清除
+  ctx.setTransform(1, 0, 0, 1, 0, 0)
+  ctx.clearRect(0, 0, canvas.width, canvas.height)
+  ctx.scale(dpr, dpr)
+  
+  // 绘制网格背景
+  ctx.strokeStyle = '#eee'
+  ctx.lineWidth = 1
+  ctx.beginPath()
+  for (let i = 0; i < 5; i++) {
+    const y = height - (height / 4) * i
+    ctx.moveTo(0, y)
+    ctx.lineTo(width, y)
+  }
+  ctx.stroke()
 
-    queueLength.value += accepted
-    rejectedCount.value += rejected
+  if (dataHistory.length < 2) return
 
-    // 生成入站粒子
-    for (let i = 0; i < Math.min(5, accepted); i++) {
-      particleId++
-      incomingParticles.value.push({ id: particleId, delay: i * 50 })
-      setTimeout(
-        () => {
-          incomingParticles.value = incomingParticles.value.filter(
-            (p) => p.id !== particleId
-          )
-        },
-        500 + i * 50
-      )
-    }
+  // 找出最大值用于Y轴缩放
+  const maxVal = Math.max(
+    2000, // 固定最小刻度
+    ...dataHistory.map(d => Math.max(d.input, d.queue))
+  )
+  const yScale = (val) => height - (val / maxVal) * height * 0.9 // 留点余量
+  const xScale = (index) => (index / (historyLength - 1)) * width
 
-    // 模拟处理请求
-    const processed = Math.min(
-      Math.floor(processRate.value / 10),
-      queueLength.value
-    )
-    queueLength.value -= processed
-    processedCount.value += processed
+  // 1. 绘制队列积压 (填充区域)
+  ctx.fillStyle = 'rgba(249, 115, 22, 0.2)' // Orange transparent
+  ctx.beginPath()
+  ctx.moveTo(0, height)
+  dataHistory.forEach((d, i) => {
+    ctx.lineTo(xScale(i), yScale(d.queue))
+  })
+  ctx.lineTo(width, height)
+  ctx.fill()
+  
+  // 队列线
+  ctx.strokeStyle = '#f97316' // Orange
+  ctx.lineWidth = 2
+  ctx.beginPath()
+  dataHistory.forEach((d, i) => {
+    if (i === 0) ctx.moveTo(xScale(i), yScale(d.queue))
+    else ctx.lineTo(xScale(i), yScale(d.queue))
+  })
+  ctx.stroke()
 
-    // 生成出站粒子
-    for (let i = 0; i < Math.min(5, processed); i++) {
-      particleId++
-      outgoingParticles.value.push({ id: particleId, delay: i * 50 })
-      setTimeout(
-        () => {
-          outgoingParticles.value = outgoingParticles.value.filter(
-            (p) => p.id !== particleId
-          )
-        },
-        500 + i * 50
-      )
-    }
-  }, 100)
+  // 2. 绘制入站流量 (蓝色线)
+  ctx.strokeStyle = '#3b82f6' // Blue
+  ctx.lineWidth = 2
+  ctx.beginPath()
+  dataHistory.forEach((d, i) => {
+    if (i === 0) ctx.moveTo(xScale(i), yScale(d.input))
+    else ctx.lineTo(xScale(i), yScale(d.input))
+  })
+  ctx.stroke()
+
+  // 3. 绘制处理流量 (绿色线)
+  ctx.strokeStyle = '#22c55e' // Green
+  ctx.lineWidth = 2
+  ctx.beginPath()
+  dataHistory.forEach((d, i) => {
+    if (i === 0) ctx.moveTo(xScale(i), yScale(d.process))
+    else ctx.lineTo(xScale(i), yScale(d.process))
+  })
+  ctx.stroke()
 }
 
-const stopSimulation = () => {
-  if (interval) {
-    clearInterval(interval)
-    interval = null
-  }
+// 模拟突发流量
+const triggerBurst = () => {
+  if (isBursting.value) return
+  isBursting.value = true
+  
+  // 3秒后恢复
+  setTimeout(() => {
+    isBursting.value = false
+  }, 3000)
 }
 
 const reset = () => {
-  stopSimulation()
-  running.value = false
   queueLength.value = 0
-  processedCount.value = 0
   rejectedCount.value = 0
-  incomingParticles.value = []
-  outgoingParticles.value = []
+  dataHistory.length = 0
+  currentRequestRate.value = 100
+  isBursting.value = false
 }
 
+const queuePercent = computed(() => {
+  return Math.min(100, (queueLength.value / queueCapacity.value) * 100)
+})
+
+const queueColor = computed(() => {
+  if (queuePercent.value > 80) return '#ef4444'
+  if (queuePercent.value > 50) return '#f97316'
+  return '#22c55e'
+})
+
+onMounted(() => {
+  if (chartCanvas.value) {
+    ctx = chartCanvas.value.getContext('2d')
+    // 解决高清屏模糊
+    const dpr = window.devicePixelRatio || 1
+    const rect = chartCanvas.value.getBoundingClientRect()
+    // 简单处理：这里由于是固定width/height属性，暂时不处理resize
+  }
+  
+  lastTime = Date.now()
+  animationFrameId = requestAnimationFrame(updateLoop)
+})
+
 onUnmounted(() => {
-  stopSimulation()
+  if (animationFrameId) {
+    cancelAnimationFrame(animationFrameId)
+  }
 })
 </script>
 
@@ -267,238 +332,227 @@ onUnmounted(() => {
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-soft);
   border-radius: 12px;
-  padding: 1.5rem;
-  margin: 1.5rem 0;
+  padding: 20px;
+  margin: 20px 0;
   font-family: var(--vp-font-family-base);
 }
 
 .header {
-  margin-bottom: 1rem;
+  margin-bottom: 24px;
 }
-
 .title {
-  font-weight: 700;
-  font-size: 1.05rem;
-}
-
-.subtitle {
-  color: var(--vp-c-text-2);
-  font-size: 0.9rem;
-  margin-top: 0.25rem;
-}
-
-.controls {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-  gap: 1rem;
-  margin-bottom: 1rem;
-}
-
-.control label {
-  display: block;
-  margin-bottom: 0.4rem;
-  font-size: 0.9rem;
-}
-
-.control input[type='range'] {
-  width: 100%;
-}
-
-.simulation {
-  display: flex;
-  gap: 0.75rem;
-  justify-content: center;
-  margin: 1rem 0;
-}
-
-.sim-btn {
-  background: var(--vp-c-brand);
-  color: #fff;
-  border: none;
-  border-radius: 8px;
-  padding: 0.6rem 1.5rem;
-  cursor: pointer;
+  font-size: 18px;
   font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+.subtitle {
+  font-size: 14px;
+  color: var(--vp-c-text-2);
+  margin-top: 4px;
+}
+
+.main-layout {
+  display: grid;
+  grid-template-columns: 300px 1fr;
+  gap: 24px;
+}
+
+@media (max-width: 768px) {
+  .main-layout {
+    grid-template-columns: 1fr;
+  }
+}
+
+.controls-panel {
+  background: var(--vp-c-bg);
+  padding: 16px;
+  border-radius: 8px;
+  border: 1px solid var(--vp-c-divider);
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.control-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.label-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.label {
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.value {
+  font-size: 13px;
+  font-family: monospace;
+  background: var(--vp-c-bg-alt);
+  padding: 2px 6px;
+  border-radius: 4px;
+}
+
+.desc {
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+}
+
+.range-input {
+  width: 100%;
+  accent-color: var(--vp-c-brand);
+}
+
+.actions {
+  margin-top: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.action-btn {
+  padding: 10px;
+  border-radius: 6px;
+  border: none;
+  font-weight: 600;
+  cursor: pointer;
   transition: all 0.2s;
 }
 
-.sim-btn:hover {
-  transform: translateY(-1px);
-  box-shadow: 0 4px 12px rgba(59, 130, 246, 0.3);
+.burst-btn {
+  background: var(--vp-c-brand);
+  color: white;
+}
+.burst-btn:hover:not(:disabled) {
+  background: var(--vp-c-brand-dark);
+}
+.burst-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
 }
 
-.sim-btn.reset {
-  background: var(--vp-c-text-2);
+.reset-btn {
+  background: var(--vp-c-bg-alt);
+  color: var(--vp-c-text-1);
+  border: 1px solid var(--vp-c-divider);
+}
+.reset-btn:hover {
+  background: var(--vp-c-bg-mute);
 }
 
-.flow-visualization {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
-  gap: 1.5rem;
-  margin: 1.5rem 0;
-  padding: 1rem;
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-}
-
-.column {
+.monitor-panel {
   display: flex;
   flex-direction: column;
-  align-items: center;
-  gap: 0.75rem;
+  gap: 16px;
 }
 
-.col-header {
-  font-weight: 600;
-  font-size: 0.9rem;
+.metrics-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 12px;
 }
 
-.rate-display {
-  font-size: 1.1rem;
-  font-weight: 700;
-  color: var(--vp-c-brand);
-}
-
-.bar-container {
-  width: 60px;
-  height: 120px;
-  background: var(--vp-c-bg-soft);
+.metric-item {
+  background: var(--vp-c-bg);
+  padding: 12px;
   border-radius: 8px;
-  position: relative;
-  overflow: hidden;
   border: 1px solid var(--vp-c-divider);
 }
 
-.bar-fill {
-  position: absolute;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  background: linear-gradient(180deg, #3b82f6, #1d4ed8);
-  border-radius: 0 0 8px 8px;
-  transition: height 0.3s ease;
+.m-label {
+  font-size: 12px;
+  color: var(--vp-c-text-2);
+  margin-bottom: 4px;
 }
 
-.bar-fill.stable {
-  background: linear-gradient(180deg, #22c55e, #16a34a);
-}
-
-.queue-info {
-  text-align: center;
-}
-
-.queue-count {
-  font-size: 1.2rem;
+.m-value {
+  font-size: 18px;
   font-weight: 700;
+  display: flex;
+  align-items: baseline;
+  gap: 4px;
 }
 
-.queue-percent {
-  font-size: 0.85rem;
+.unit {
+  font-size: 12px;
+  font-weight: 400;
+  opacity: 0.7;
+}
+
+.m-value.blue { color: #3b82f6; }
+.m-value.green { color: #22c55e; }
+.m-value.orange { color: #f97316; }
+.m-value.red { color: #ef4444; }
+
+.m-bar-bg {
+  height: 4px;
+  background: var(--vp-c-bg-soft);
+  border-radius: 2px;
+  margin-top: 8px;
+  overflow: hidden;
+}
+
+.m-bar-fill {
+  height: 100%;
+  transition: width 0.2s;
+}
+
+.chart-container {
+  flex: 1;
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  min-height: 250px;
+}
+
+canvas {
+  width: 100%;
+  height: 100%;
+  flex: 1;
+}
+
+.chart-legend {
+  display: flex;
+  gap: 16px;
+  justify-content: center;
+  margin-top: 8px;
+  font-size: 12px;
   color: var(--vp-c-text-2);
 }
 
-.queue-bar-container {
-  width: 100%;
-  height: 24px;
-  background: var(--vp-c-bg-soft);
-  border-radius: 12px;
-  overflow: hidden;
-  border: 1px solid var(--vp-c-divider);
-  position: relative;
+.legend-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
 }
 
-.queue-bar {
-  height: 100%;
-  transition:
-    width 0.3s ease,
-    background 0.3s ease;
-}
-
-.queue-bar.normal {
-  background: linear-gradient(90deg, #22c55e, #16a34a);
-}
-
-.queue-bar.warning {
-  background: linear-gradient(90deg, #f59e0b, #d97706);
-}
-
-.queue-bar.critical {
-  background: linear-gradient(90deg, #ef4444, #dc2626);
-}
-
-.queue-status-text {
-  font-size: 0.85rem;
-  text-align: center;
-  margin-top: 0.25rem;
-}
-
-.particles {
-  position: relative;
-  height: 60px;
-  width: 100%;
-}
-
-.particle {
-  position: absolute;
+.dot {
   width: 8px;
   height: 8px;
-  background: var(--vp-c-brand);
   border-radius: 50%;
-  animation: fall 0.5s linear infinite;
-}
-
-.particle.processed {
-  background: #22c55e;
-}
-
-@keyframes fall {
-  0% {
-    transform: translateY(0);
-    opacity: 1;
-  }
-  100% {
-    transform: translateY(60px);
-    opacity: 0;
-  }
-}
-
-.metrics {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
-  gap: 1rem;
-  margin-top: 1rem;
-}
-
-.metric-card {
-  background: var(--vp-c-bg);
-  border-radius: 10px;
-  padding: 1rem;
-  text-align: center;
-  border: 1px solid var(--vp-c-divider);
-}
-
-.metric-label {
-  font-size: 0.85rem;
-  color: var(--vp-c-text-2);
-  margin-bottom: 0.5rem;
-}
-
-.metric-value {
-  font-size: 1.3rem;
-  font-weight: 700;
-  color: var(--vp-c-text-1);
-}
-
-.metric-value.error {
-  color: #ef4444;
 }
+.dot.blue { background: #3b82f6; }
+.dot.green { background: #22c55e; }
+.dot.orange { background: #f97316; }
 
 .scenario-tips {
-  margin-top: 1rem;
-  padding: 0.75rem 1rem;
+  margin-top: 16px;
   background: rgba(59, 130, 246, 0.1);
+  border: 1px solid rgba(59, 130, 246, 0.2);
   border-radius: 8px;
-  font-size: 0.9rem;
+  padding: 12px;
+  display: flex;
+  gap: 12px;
+  font-size: 14px;
   line-height: 1.5;
+  color: var(--vp-c-text-1);
 }
 </style>
diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js
index 9a3296d..f832d6e 100644
--- a/docs/.vitepress/theme/index.js
+++ b/docs/.vitepress/theme/index.js
@@ -77,6 +77,7 @@ import GitBranchMergeDemo from './components/appendix/git-intro/GitBranchMergeDe
 import GitConflictDemo from './components/appendix/git-intro/GitConflictDemo.vue'
 import GitStashDemo from './components/appendix/git-intro/GitStashDemo.vue'
 import GitRemoteDemo from './components/appendix/git-intro/GitRemoteDemo.vue'
+import GitScenariosDemo from './components/appendix/git-intro/GitScenariosDemo.vue'
 // （保留网络相关，未修改）
 import NetworkLayers from './components/appendix/web-basics/NetworkLayers.vue'
 import TcpUdpComparison from './components/appendix/web-basics/TcpUdpComparison.vue'
@@ -118,6 +119,13 @@ import BigFrontendScopeDemo from './components/appendix/web-basics/BigFrontendSc
 import AiEvolutionDemo from './components/appendix/ai-history/AiEvolutionDemo.vue'
 import RuleBasedVsLearningDemo from './components/appendix/ai-history/RuleBasedVsLearningDemo.vue'
 import PerceptronDemo from './components/appendix/ai-history/PerceptronDemo.vue'
+import AIEvolutionTimelineDemo from './components/appendix/ai-history/AIEvolutionTimelineDemo.vue'
+import CombinatorialExplosionDemo from './components/appendix/ai-history/CombinatorialExplosionDemo.vue'
+import NeuralNetworkVisualizationDemo from './components/appendix/ai-history/NeuralNetworkVisualizationDemo.vue'
+import BackpropagationDemo from './components/appendix/ai-history/BackpropagationDemo.vue'
+import AttentionMechanismDemo from './components/appendix/ai-history/AttentionMechanismDemo.vue'
+import DiscriminativeVsGenerativeDemo from './components/appendix/ai-history/DiscriminativeVsGenerativeDemo.vue'
+import GPTEvolutionDemo from './components/appendix/ai-history/GPTEvolutionDemo.vue'
 
 import ImperativeVsDeclarativeDemo from './components/appendix/web-basics/ImperativeVsDeclarativeDemo.vue'
 import ComponentReusabilityDemo from './components/appendix/web-basics/ComponentReusabilityDemo.vue'
@@ -160,6 +168,7 @@ import ProductCacheDemo from './components/appendix/cache-design/ProductCacheDem
 // Auth Design Components
 import AuthEvolutionDemo from './components/appendix/auth-design/AuthEvolutionDemo.vue'
 import AuthBasicsDemo from './components/appendix/auth-design/AuthBasicsDemo.vue'
+import AuthInteractiveLoginDemo from './components/appendix/auth-design/AuthInteractiveLoginDemo.vue'
 import AuthNvsAuthZDemo from './components/appendix/auth-design/AuthNvsAuthZDemo.vue'
 import SessionCookieDemo from './components/appendix/auth-design/SessionCookieDemo.vue'
 import JWTWorkflowDemo from './components/appendix/auth-design/JWTWorkflowDemo.vue'
@@ -187,6 +196,7 @@ import FewShotDemo from './components/appendix/prompt-engineering/FewShotDemo.vu
 import ChainOfThoughtDemo from './components/appendix/prompt-engineering/ChainOfThoughtDemo.vue'
 
 // Context Engineering Components
+import AgentContextFlow from './components/appendix/context-engineering/AgentContextFlow.vue'
 import ContextWindowVisualizer from './components/appendix/context-engineering/ContextWindowVisualizer.vue'
 import SlidingWindowDemo from './components/appendix/context-engineering/SlidingWindowDemo.vue'
 import SelectiveContextDemo from './components/appendix/context-engineering/SelectiveContextDemo.vue'
@@ -318,6 +328,7 @@ export default {
     app.component('GitConflictDemo', GitConflictDemo)
     app.component('GitStashDemo', GitStashDemo)
     app.component('GitRemoteDemo', GitRemoteDemo)
+    app.component('GitScenariosDemo', GitScenariosDemo)
     app.component('NetworkLayers', NetworkLayers)
     app.component('TcpUdpComparison', TcpUdpComparison)
     app.component('SubnetCalculator', SubnetCalculator)
@@ -357,6 +368,19 @@ export default {
     app.component('AiEvolutionDemo', AiEvolutionDemo)
     app.component('RuleBasedVsLearningDemo', RuleBasedVsLearningDemo)
     app.component('PerceptronDemo', PerceptronDemo)
+    app.component('AIEvolutionTimelineDemo', AIEvolutionTimelineDemo)
+    app.component('CombinatorialExplosionDemo', CombinatorialExplosionDemo)
+    app.component(
+      'NeuralNetworkVisualizationDemo',
+      NeuralNetworkVisualizationDemo
+    )
+    app.component('BackpropagationDemo', BackpropagationDemo)
+    app.component('AttentionMechanismDemo', AttentionMechanismDemo)
+    app.component(
+      'DiscriminativeVsGenerativeDemo',
+      DiscriminativeVsGenerativeDemo
+    )
+    app.component('GPTEvolutionDemo', GPTEvolutionDemo)
 
     app.component('ImperativeVsDeclarativeDemo', ImperativeVsDeclarativeDemo)
     app.component('ComponentReusabilityDemo', ComponentReusabilityDemo)
@@ -399,6 +423,7 @@ export default {
     // Auth Design Components Registration
     app.component('AuthEvolutionDemo', AuthEvolutionDemo)
     app.component('AuthBasicsDemo', AuthBasicsDemo)
+    app.component('AuthInteractiveLoginDemo', AuthInteractiveLoginDemo)
     app.component('AuthNvsAuthZDemo', AuthNvsAuthZDemo)
     app.component('SessionCookieDemo', SessionCookieDemo)
     app.component('JWTWorkflowDemo', JWTWorkflowDemo)
@@ -426,6 +451,7 @@ export default {
     app.component('ChainOfThoughtDemo', ChainOfThoughtDemo)
 
     // Context Engineering Components Registration
+    app.component('AgentContextFlow', AgentContextFlow)
     app.component('ContextWindowVisualizer', ContextWindowVisualizer)
     app.component('SlidingWindowDemo', SlidingWindowDemo)
     app.component('SelectiveContextDemo', SelectiveContextDemo)
diff --git a/docs/zh-cn/appendix/ai-evolution.md b/docs/zh-cn/appendix/ai-evolution.md
index 665b46a..cb5ec44 100644
--- a/docs/zh-cn/appendix/ai-evolution.md
+++ b/docs/zh-cn/appendix/ai-evolution.md
@@ -1,24 +1,34 @@
-# 人工智能进化史：从 "逻辑" 到 "直觉" (Interactive Intro)
+# 人工智能进化史：从"逻辑"到"直觉"（交互式教程）
 
-> 💡 **学习指南**：本章节通过交互式演示，带你梳理人工智能 70 年的发展脉络。从最早的下棋程序，到今天能写诗作画的 ChatGPT。
+> 💡 **学习指南**：本章节无需编程基础，通过交互式演示带你梳理人工智能 70 年的发展脉络。从最早的下棋程序，到今天能写诗作画的 ChatGPT。我们将深入理解 AI 从"人工规则"到"机器学习"的进化历程。
 
 <AiEvolutionDemo />
 
 ## 0. 引言：机器能思考吗？
 
-图灵在 1950 年提出了这个问题。
-为了回答它，人类进行了长达半个多世纪的探索。
+1950 年，艾伦·图灵在论文《计算机器与智能》中提出了这个问题：
+**"机器能思考吗？"**
 
-我们走过弯路（试图穷举规则），也经历过寒冬（算力不足），最终在模仿人脑（神经网络）的道路上取得了突破。
+为了回答它，人类进行了长达半个多世纪的探索。我们走过弯路（试图穷举规则），也经历过寒冬（算力不足），最终在模仿人脑（神经网络）的道路上取得了突破。
+
+AI 的进化史，就是人类探索"如何让机器拥有智能"的历史。这条探索之路经历了三个主要阶段：
+
+1.  **符号主义**：教机器"守规矩"——人工写规则
+2.  **连接主义**：教机器"像人脑一样思考"——神经网络学习
+3.  **生成式人工智能**：机器有了"创造力"——大语言模型
+
+本教程将带你从零开始，一步步理解这些范式的演变。
+
+<AIEvolutionTimelineDemo />
 
 ---
 
-## 1. 符号主义：教机器"守规矩" (1950s - 1980s)
+## 1. 符号主义：教机器"守规矩"（20世纪50年代 - 80年代）
 
 早期的 AI 科学家认为：智慧就是**逻辑推理**。
 只要我们把世界上的所有知识都写成 `If...Then...` 的规则，机器就能像人一样聪明。
 
-这被称为**专家系统 (Expert Systems)**。
+这被称为**专家系统**或**符号主义人工智能**。
 
 ### 1.1 什么是"基于规则"？
 
@@ -27,7 +37,60 @@
 - 如果看到红灯，就停下。
 - 如果下雨，就带伞。
 
-### 1.2 交互演示：规则 vs 学习
+在代码中，这表现为：
+
+```javascript
+// 基于规则的 AI 示例
+function decideTrafficLight(color) {
+  if (color === 'red') {
+    return 'stop'
+  } else if (color === 'yellow') {
+    return 'caution'
+  } else if (color === 'green') {
+    return 'go'
+  }
+}
+```
+
+### 1.2 专家系统的巅峰：MYCIN
+
+1970 年代，斯坦福大学开发的 MYCIN 系统能诊断血液感染，准确率达到专家水平。
+
+它的工作原理是：
+
+```lisp
+;; MYCIN 系统的规则示例 (伪代码)
+(IF
+  (organism IS gram-positive)
+  (morphology IS coccus)
+  (growth-chains IS chains)
+THEN
+  (identity IS 0.7 streptococcus))
+```
+
+_数据示例 (知识库格式)_：
+```json
+// 专家系统知识库示例
+{
+  "rules": [
+    {
+      "id": "RULE-001",
+      "conditions": ["traffic_light == red", "speed > 0"],
+      "action": "brake",
+      "priority": 1
+    },
+    {
+      "id": "RULE-002",
+      "conditions": ["weather == rainy", "visibility < 100m"],
+      "action": "turn_on_lights",
+      "priority": 2
+    }
+  ]
+  // 系统按优先级依次匹配规则，遇到匹配就执行
+}
+```
+
+### 1.3 交互演示：规则 vs 学习
 
 下方的演示展示了两种方式的区别。
 
@@ -36,55 +99,230 @@
 
 <RuleBasedVsLearningDemo />
 
-**局限性**：你能写出"识别猫"的规则吗？
-"有胡须"？老鼠也有。"有尖耳朵"？狗也有。
-现实世界太复杂，规则写不完。这就是符号主义 AI 衰落的原因。
+### 1.4 符号主义的局限性
+
+规则看起来很完美，但现实世界太复杂了。
+
+<CombinatorialExplosionDemo />
+
+**问题 1：组合爆炸**
+- 试图写下"识别猫"的所有规则？不可能！
+- "有胡须"？老鼠也有。
+- "有尖耳朵"？狗也有。
+- "毛茸茸的"？兔子也是。
+- 现实世界有无限边界情况，规则永远写不完。
+
+**问题 2：无法处理不确定性**
+- 如果规则冲突怎么办？
+- 如果遇到没见过的情况怎么办？
+- 规则系统很"脆弱"，缺少人类常识。
+
+> ⚠️ **教训**：试图用有限规则描述无限现实，注定失败。这导致了 1980 年代的**AI 寒冬**。
 
 ---
 
-## 2. 连接主义：教机器"像人脑一样思考" (2010s+)
+## 2. 连接主义：教机器"像人脑一样思考"（21世纪10年代至今）
 
-既然规则写不完，不如让机器自己学？
+既然规则写不完，不如换个思路：**让机器自己学**？
 科学家开始模仿人脑的结构——**神经元**。
 
-### 2.1 感知机 (Perceptron)
+这就是**连接主义**的核心思想。
 
-这是最简单的神经元模型。它接收多个输入，根据**权重 (Weight)** 加权求和，如果超过某个**阈值 (Bias)**，就激活。
+### 2.1 人脑的启示
+
+人脑有约 860 亿个神经元，每个神经元通过突触连接成千上万个其他神经元。
+
+**关键发现**：
+- 单个神经元很"笨"（只是兴奋或不兴奋）
+- 但几百亿个神经元连在一起，就产生了智能
+
+### 2.2 感知机
+
+1957 年，康奈尔大学的 Frank Rosenblatt 发明了感知机——这是最简单的人工神经元。
+
+它的工作原理：
+
+1.  **接收输入**：从多个"突触"接收信号（$x_1, x_2, ...$）
+2.  **加权求和**：每个输入有对应的**权重**，代表重要性
+3.  **激活判断**：如果总和超过某个**阈值（偏置）**，就激活（输出 1）
 
 $$ Output = \begin{cases} 1 & \text{if } \sum (w_i \cdot x_i) + b > 0 \\ 0 & \text{otherwise} \end{cases} $$
 
-听起来很复杂？动手试一下！
+### 2.3 交互演示：玩转神经元
 
-### 2.2 交互演示：玩转神经元
+调整下方的**权重**和**偏置**，看看能否控制神经元的输出。
 
-调整下方的 **Weights (权重)** 和 **Bias (偏置)**，看看能否控制神经元的输出。
-
-- **Weights ($w$)**：代表输入的"重要性"。$w$ 越大，这个输入对结果影响越大。
-- **Bias ($b$)**：代表神经元的"门槛"。$b$ 越小，神经元越容易兴奋（输出 1）。
+- **权重（$w$）**：代表输入的"重要性"。$w$ 越大，这个输入对结果影响越大。
+- **偏置（$b$）**：代表神经元的"门槛"。$b$ 越小，神经元越容易兴奋（输出 1）。
 
 <PerceptronDemo />
 
-当几十亿个这样的神经元连接在一起，奇迹就发生了——这就是**深度学习 (Deep Learning)**。
+### 2.4 从单神经元到深度学习
+
+单个神经元能做什么？只能做简单分类（比如判断"苹果还是樱桃"）。
+
+但如果把神经元分层连接：
+
+```
+输入层 (图片像素)
+    ↓
+隐藏层 1 (识别边缘)
+    ↓
+隐藏层 2 (识别形状)
+    ↓
+隐藏层 3 (识别物体部件)
+    ↓
+输出层 (识别物体)
+```
+
+这就是**神经网络**。当网络有很多层时，我们称之为**深度学习**。
+
+<NeuralNetworkVisualizationDemo />
+
+### 2.5 神经网络是如何学习的？
+
+不像专家系统需要人写规则，神经网络通过**看数据**自己学。
+
+**学习过程（反向传播）**：
+1.  **前向传播**：输入数据，得到预测结果
+2.  **计算误差**：对比预测和真实答案
+3.  **反向传播**：根据误差调整每个神经元的权重
+4.  **重复**：重复几百万次，直到误差足够小
+
+<BackpropagationDemo />
+
+_数据示例 (训练数据格式)_：
+```json
+// 图像分类训练数据示例
+{
+  "dataset": "cats_vs_dogs",
+  "samples": [
+    {
+      "image": "cat_001.jpg",
+      "label": 1,  // 1 = 猫
+      "features": [0.2, 0.8, 0.5, ...]  // 提取的特征向量
+    },
+    {
+      "image": "dog_001.jpg",
+      "label": 0,  // 0 = 狗
+      "features": [0.7, 0.3, 0.9, ...]
+    }
+  ]
+  // 神经网络会自动学习：什么样的 feature 组合更可能是猫
+}
+```
+
+### 2.6 连接主义的突破：2012 年 AlexNet
+
+2012 年，AlexNet 在 ImageNet 竞赛中以压倒性优势夺冠，标志着深度学习时代的到来。
+
+**关键因素**：
+- **大数据**：ImageNet 提供了 1400 万张标注图片
+- **大算力**：GPU 的并行计算能力让训练深度网络成为可能
+- **新算法**：ReLU 激活函数、Dropout 正则化等技术突破
+
+### 2.7 连接主义的局限
+
+深度学习很强大，但也不是完美的：
+
+- **黑盒问题**：虽然能识别猫，但我们说不清"它是怎么识别的"
+- **数据饥渴**：需要海量标注数据，获取成本高
+- **缺乏常识**：能认猫，但不知道"猫会怕狗"
 
 ---
 
-## 3. 生成式 AI：机器有了"创造力" (2020s+)
+## 3. 生成式人工智能：机器有了"创造力"（21世纪20年代至今）
 
 以前的 AI 主要是**判别式**（这是猫还是狗？）。
 现在的 AI 是**生成式**（画一只猫！）。
 
 这一切的背后，是 **Transformer** 架构的诞生。它让 AI 学会了理解上下文，学会了"举一反三"。
 
-> 关于大语言模型 (LLM) 的详细原理，请移步下一章：[大语言模型入门](./llm-intro.md)
+### 3.1 从"识别"到"创造"
+
+传统深度学习（判别式模型）：
+- 输入：一张图
+- 输出：这是猫（概率 98%）
+
+生成式 AI：
+- 输入：一句话"一只戴着墨镜的猫"
+- 输出：生成一张对应的图片
+
+<DiscriminativeVsGenerativeDemo />
+
+### 3.2 Transformer：AI 的"瑞士军刀"
+
+2017 年，Google 发表论文《Attention Is All You Need》（注意力机制就是你所需的全部），提出 Transformer 架构。
+
+它的核心创新：**注意力机制**
+
+**原理**：让模型在处理一个词时，能"关注"到句子中其他相关的词。
+
+例如："小明把苹果给了**他**的母亲"
+
+当模型处理"他"时，注意力机制会让它关注到"小明"，从而理解"他"指代的是小明。
+
+<AttentionMechanismDemo />
+
+### 3.3 GPT：从文本生成到通用智能
+
+2018 年，OpenAI 发布 GPT-1（生成式预训练变换器）。
+
+**核心思想**：
+1.  **预训练**：在海量文本上学习"预测下一个词"
+2.  **微调**：在特定任务上调整（比如问答、翻译）
+
+从 GPT-1 (2018) → GPT-2 (2019) → GPT-3 (2020) → GPT-4 (2023)
+- 参数量从 1.17 亿 → 1750 亿 → 1.8 万亿（估计）
+- 能力从文本生成 → 多模态（图片、音频、视频）
+
+<GPTEvolutionDemo />
+
+### 3.4 生成式人工智能的局限
+
+虽然强大，但也存在问题：
+
+- **幻觉**：一本正经地胡说八道
+- **偏见放大**：从训练数据中学到人类偏见
+- **不可解释**：仍然是个黑盒，不知道内部怎么运作
 
 ---
 
-## 4. 总结
+## 4. AI 范式对比总结
 
-| 时代          | 核心理念        | 代表产物                  | 局限                         |
-| :------------ | :-------------- | :------------------------ | :--------------------------- |
-| **符号主义**  | 智慧 = 规则     | 深蓝 (下棋), 医疗诊断系统 | 无法处理模糊、复杂的现实世界 |
-| **连接主义**  | 智慧 = 神经网络 | AlphaGo, 人脸识别         | 需要海量数据，是个"黑盒"     |
-| **生成式 AI** | 智慧 = 通用理解 | ChatGPT, Midjourney       | 幻觉 (一本正经胡说八道)      |
+| 时代                | 核心理念        | 代表产物                  | 优势                      | 局限                         |
+| :------------------ | :-------------- | :------------------------ | :------------------------ | :--------------------------- |
+| **符号主义**        | 智慧 = 规则     | 深蓝（下棋）、MYCIN（诊断） | 可解释性强，逻辑清晰       | 无法处理模糊、复杂的现实世界 |
+| **连接主义**        | 智慧 = 神经网络 | AlphaGo、人脸识别         | 能处理复杂模式，性能强大   | 需要海量数据，是个"黑盒"     |
+| **生成式人工智能** | 智慧 = 通用理解 | ChatGPT、Midjourney       | 能创造新内容，理解上下文   | 幻觉、偏见、不可解释         |
 
-AI 的进化，就是从"人工设定规则"到"机器自动学习数据"的过程。
+**AI 的进化趋势**：
+
+1.  **从人工到自动**：从人写规则 → 机器自动学习
+2.  **从单一到通用**：从下棋专用 → 通用人工智能
+3.  **从判别到生成**：从分类识别 → 创造新内容
+
+> 关于大语言模型的详细原理，请移步下一章：[大语言模型入门](./llm-intro.md)
+
+---
+
+## 5. 名词速查表
+
+| 名词               | 英文原文                   | 解释                                                                                       |
+| :----------------- | :------------------------- | :----------------------------------------------------------------------------------------- |
+| **符号主义**       | Symbolic AI                | 基于规则的人工智能。认为智能可以用逻辑规则表示。代表：专家系统、深蓝。                        |
+| **专家系统**       | Expert Systems             | 符号主义的代表产物。通过人工编写大量规则来模拟专家决策。代表：MYCIN（医疗诊断）。              |
+| **连接主义**       | Connectionism              | 基于神经网络的人工智能。模仿人脑神经元连接结构，通过数据自动学习。                           |
+| **感知机**         | Perceptron                 | 最简单的神经网络单元。接收多个输入，加权求和后通过激活函数输出。                             |
+| **神经网络**       | Neural Network             | 由多个感知机分层连接组成的模型。通过调整权重来学习数据中的模式。                             |
+| **深度学习**       | Deep Learning              | 使用**多层**神经网络的学习方法。能自动提取层次化特征（边缘 → 形状 → 物体）。                 |
+| **反向传播**       | Backpropagation            | 神经网络的学习算法。通过计算预测误差，反向调整每层的权重，逐步优化模型。                     |
+| **生成式人工智能** | Generative AI              | 能**创造新内容**的人工智能（文本、图片、音频等），而非仅仅是分类或识别。代表：ChatGPT、Midjourney。 |
+| **判别式人工智能** | Discriminative AI          | 用于**分类**的人工智能（如：这是猫还是狗？）。传统深度学习大多是判别式的。                     |
+| **Transformer**    | Transformer                | 2017 年由 Google 提出的架构，基于注意力机制。是现代大语言模型（GPT、BERT）的基础。          |
+| **注意力机制**     | Attention Mechanism        | 让模型在处理一个元素时，能动态"关注"其他相关元素的技术。是 Transformer 的核心。             |
+| **GPT**            | Generative Pre-trained Transformer | OpenAI 的系列模型。通过"预训练 + 微调"范式，在大量文本上学习生成能力。              |
+| **预训练**         | Pre-training               | 在大规模无标注数据上进行初步训练，学习通用知识（如语言规律）。                               |
+| **微调**           | Fine-tuning                | 在预训练模型基础上，使用特定任务的小规模数据进行调整，使模型适应具体应用。                   |
+| **幻觉**           | Hallucination              | 生成式人工智能模型"自信地编造错误内容"的现象。如 ChatGPT 编造不存在的论文或事实。            |
+| **通用人工智能**   | Artificial General Intelligence | 像人类一样具备多领域智能、能自主学习推理的人工智能（尚未实现）。                    |
diff --git a/docs/zh-cn/appendix/api-intro.md b/docs/zh-cn/appendix/api-intro.md
new file mode 100644
index 0000000..7d35849
--- /dev/null
+++ b/docs/zh-cn/appendix/api-intro.md
@@ -0,0 +1,314 @@
+# API 入门：软件世界的"服务员"
+
+> 💡 **学习指南**：本章节无需编程基础，通过交互式演示带你深入了解 API（应用程序接口）。我们将从最基础的"什么是 API"讲起，到如何阅读 API 文档，再到实际调用 API。
+
+<ApiQuickStartDemo />
+
+## 0. 引言：无处不在的"桥梁"
+
+你用微信登录第三方 APP 时，是谁在幕后传递信息？
+你在淘宝查询物流时，是谁帮你连接快递公司的数据？
+你用 AI 写代码时，是谁把你的需求传给大模型？
+
+这背后都有一个功臣：**API (Application Programming Interface)**。
+
+如果软件是"餐厅"，那 API 就是"服务员"。
+你需要什么（数据、功能），告诉服务员（调用 API），服务员会去厨房（服务器）取来，端到你面前（返回结果）。
+
+### 0.1 为什么需要 API？
+
+想象一下，如果没有服务员（API）：
+
+- ❌ 每个顾客都要自己冲进厨房找菜
+- ❌ 厨房会被搞乱，效率极低
+- ❌ 顾客需要知道厨房怎么运作
+
+有了服务员（API）：
+
+- ✅ 顾客只需看菜单（API 文档）点餐
+- ✅ 服务员传递订单，厨房专注做菜
+- ✅ 顾客不需要知道厨房怎么运作
+
+**关键点**：API 让不同软件之间能够"对话"，而不需要了解对方的内部实现。
+
+---
+
+## 1. 第一步：理解 API 的本质
+
+### 1.1 什么是 API？
+
+**API (Application Programming Interface)** = 应用程序编程接口。
+
+翻译成人话：**软件之间的"约定"和"服务员"**。
+
+- **Application（应用）**：两个不同的软件系统（如你的 APP 和微信服务器）
+- **Programming（编程）**：通过代码来交互
+- **Interface（接口）**：双方约定的"沟通方式"
+
+<ApiConceptDemo />
+
+**关键点**：API 定义了：
+- 你可以请求什么（有哪些功能）
+- 怎么请求（格式、参数）
+- 会返回什么（数据结构）
+
+### 1.2 API 的类型
+
+API 有很多种形式，最常见的有：
+
+| 类型 | 例子 | 说明 |
+| :--- | :--- | :--- |
+| **Web API** | REST API、GraphQL | 通过 HTTP 协议调用，最常见 |
+| **库 API** | React、Vue | 代码库提供的函数接口 |
+| **系统 API** | 文件系统 API | 操作系统提供的功能接口 |
+
+本教程重点讲解 **Web API**，因为它最常用，也最容易理解。
+
+---
+
+## 2. API 是怎么工作的？
+
+### 2.1 请求-响应模型
+
+API 的工作原理就像"点餐-上菜"：
+
+1. **发起请求**：你告诉服务员要什么（调用 API）
+2. **处理请求**：服务员去厨房传达（服务器处理）
+3. **返回结果**：服务员把菜端上来（返回数据）
+
+<RequestResponseFlow />
+
+### 2.2 HTTP 方法：四种基本操作
+
+在 Web API 中，我们使用 HTTP 方法来表达不同的操作：
+
+| 方法 | 作用 | 类比 |
+| :--- | :--- | :--- |
+| **GET** | 获取数据 | "给我看看菜单" |
+| **POST** | 创建数据 | "我要点这道菜" |
+| **PUT** | 更新数据 | "把这道菜换成辣的" |
+| **DELETE** | 删除数据 | "取消这道菜" |
+
+<ApiMethodDemo />
+
+**关键点**：REST API 遵循"统一接口"原则，用这四种方法就能完成所有操作。
+
+---
+
+## 3. 认识 API 文档
+
+### 3.1 什么是 API 文档？
+
+API 文档就像**餐厅的菜单**，它告诉你：
+
+- 📋 **有哪些菜可以点**（API 提供哪些功能）
+- 💰 **每个菜的名字和价格**（接口地址、参数）
+- 📝 **菜的详细说明**（返回数据格式）
+- ⚠️ **注意事项**（限制条件、错误码）
+
+<ApiDocumentDemo />
+
+### 3.2 API 文档的组成
+
+一个完整的 API 文档通常包含：
+
+#### 1️⃣ 基本信息
+```
+接口地址：https://api.example.com/users
+请求方法：GET
+功能说明：获取用户列表
+```
+
+#### 2️⃣ 请求参数
+```
+参数名    类型    必填    说明
+page      number  否      页码，默认 1
+limit     number  否      每页数量，默认 20
+```
+
+#### 3️⃣ 返回示例
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "张三",
+      "email": "zhangsan@example.com"
+    }
+  ]
+}
+```
+
+#### 4️⃣ 错误码说明
+```
+400 - 参数错误
+401 - 未授权
+404 - 资源不存在
+500 - 服务器错误
+```
+
+---
+
+## 4. 实战：如何使用 API？
+
+### 4.1 阅读文档的步骤
+
+拿到一个新的 API，按以下步骤操作：
+
+**第 1 步：找到文档入口**
+- 通常在官网的 "Developers" 或 "API" 板块
+- 常见的文档平台：Swagger、Apiary、Readme.io
+
+**第 2 步：理解接口功能**
+- 看接口名称和说明，判断是否是你需要的功能
+- 注意请求方法（GET/POST/PUT/DELETE）
+
+**第 3 步：查看请求参数**
+- 必填参数：一定要提供
+- 可选参数：根据需要提供
+- 参数类型：字符串、数字、布尔值
+
+**第 4 步：看返回示例**
+- 了解成功时的返回格式
+- 查看错误时的返回格式
+
+**第 5 步：尝试调用**
+- 可以用在线工具（如 Postman、curl）
+- 或者在代码中调用
+
+<ApiPlayground />
+
+### 4.2 真实案例：调用天气 API
+
+让我们调用一个真实的天气 API 来查询北京的天气。
+
+<RealWorldApiDemo />
+
+**代码示例**：
+
+```javascript
+// 使用 JavaScript 调用 API
+fetch('https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Beijing')
+  .then(response => response.json())
+  .then(data => {
+    console.log('北京天气：', data.current.temp_c, '°C');
+    console.log('天气状况：', data.current.condition.text);
+  })
+  .catch(error => {
+    console.error('出错了：', error);
+  });
+```
+
+```python
+# 使用 Python 调用 API
+import requests
+
+response = requests.get('https://api.weatherapi.com/v1/current.json', params={
+    'key': 'YOUR_KEY',
+    'q': 'Beijing'
+})
+
+data = response.json()
+print(f"北京天气：{data['current']['temp_c']}°C")
+print(f"天气状况：{data['current']['condition']['text']}")
+```
+
+---
+
+## 5. 常见问题与最佳实践
+
+### 5.1 为什么我的 API 调用失败了？
+
+常见错误：
+
+| 错误码 | 原因 | 解决方案 |
+| :--- | :--- | :--- |
+| **400** | 参数错误 | 检查参数名、类型、格式 |
+| **401** | 未授权 | 检查 API Key 是否正确 |
+| **404** | 接口不存在 | 确认 URL 是否正确 |
+| **429** | 请求过于频繁 | 降低请求频率或联系提供方 |
+| **500** | 服务器错误 | 稍后重试或联系技术支持 |
+
+### 5.2 最佳实践
+
+✅ **使用 API 时要注意**：
+
+1. **阅读文档**：不要猜测，仔细看文档
+2. **处理错误**：不要假设调用总是成功
+3. **控制频率**：避免被限流（Rate Limit）
+4. **保护密钥**：不要把 API Key 写在公开代码里
+5. **缓存数据**：相同数据不要重复请求
+
+❌ **常见错误**：
+
+- 不看文档就盲目调用
+- 不处理错误响应
+- 密钥泄露到 GitHub
+- 无限重试导致被封禁
+
+---
+
+## 6. 总结与进阶
+
+恭喜你！现在你已经掌握了 API 的基础知识。
+
+### 6.1 核心知识点回顾
+
+- ✅ API 是软件之间的"服务员"和"桥梁"
+- ✅ API 工作原理：请求 → 处理 → 响应
+- ✅ HTTP 方法：GET（查）、POST（增）、PUT（改）、DELETE（删）
+- ✅ API 文档包含：接口地址、参数、返回格式、错误码
+- ✅ 调用 API 的五步法：找文档 → 理解功能 → 查参数 → 看示例 → 尝试调用
+
+### 6.2 学习路线
+
+1. **入门**（今天）
+   - 理解 API 的概念
+   - 会阅读简单的 API 文档
+   - 能用工具（Postman）调用 API
+
+2. **进阶**（1 周）
+   - 在代码中调用 API
+   - 处理认证（API Key、OAuth）
+   - 处理分页、过滤等高级功能
+
+3. **深入**（持续）
+   - 学习 GraphQL（REST 的替代方案）
+   - 设计自己的 API
+   - API 性能优化和安全
+
+### 6.3 推荐资源
+
+- **练习平台**：
+  - [JSONPlaceholder](https://jsonplaceholder.typicode.com/) - 假数据 API，用于练习
+  - [Public APIs](https://publicapis.dev/) - 收录了大量免费 API
+
+- **文档工具**：
+  - [Postman](https://www.postman.com/) - API 调试工具
+  - [Swagger Editor](https://editor.swagger.io/) - API 文档编辑器
+
+- **学习资料**：
+  - [REST API Tutorial](https://restfulapi.net/)
+  - [MDN Web API 文档](https://developer.mozilla.org/zh-CN/docs/Web/API)
+
+---
+
+## 7. 名词速查表
+
+| 名词 | 英文 | 解释 |
+| :--- | :--- | :--- |
+| **API** | Application Programming Interface | 应用程序编程接口，软件之间的"服务员" |
+| **HTTP** | HyperText Transfer Protocol | 超文本传输协议，Web API 的基础 |
+| **REST** | Representational State Transfer | 一种 API 设计风格，最常见 |
+| **GET** | - | HTTP 方法，用于获取数据 |
+| **POST** | - | HTTP 方法，用于创建数据 |
+| **PUT** | - | HTTP 方法，用于更新数据 |
+| **DELETE** | - | HTTP 方法，用于删除数据 |
+| **Endpoint** | - | 接口地址，如 /users |
+| **Request** | - | 请求，客户端发给服务器 |
+| **Response** | - | 响应，服务器返回给客户端 |
+| **JSON** | JavaScript Object Notation | 一种数据格式，API 常用 |
+| **Authentication** | - | 认证，验证你是谁 |
+| **Rate Limit** | - | 限流，控制请求频率 |
diff --git a/docs/zh-cn/appendix/auth-design.md b/docs/zh-cn/appendix/auth-design.md
index 1960ae4..8b5341b 100644
--- a/docs/zh-cn/appendix/auth-design.md
+++ b/docs/zh-cn/appendix/auth-design.md
@@ -27,6 +27,12 @@
 
 <AuthBasicsDemo />
 
+### 0.2 交互式演示：登录流程
+
+让我们通过一个真实的登录演示，来理解认证和授权是如何工作的。
+
+<AuthInteractiveLoginDemo />
+
 **关键点**：鉴权是第一道防线，所有敏感操作都必须先验证身份。
 
 ---
diff --git a/docs/zh-cn/appendix/cache-design.md b/docs/zh-cn/appendix/cache-design.md
index 1e8d2ec..3f56bb4 100644
--- a/docs/zh-cn/appendix/cache-design.md
+++ b/docs/zh-cn/appendix/cache-design.md
@@ -6,26 +6,181 @@
 
 ## 0. 引言：看不见的"加速器"
 
-你刷朋友圈时，为什么几秒钟就能加载出几百张图片？
-你查询订单时，为什么瞬间就能看到几个月前的数据？
+你有没有想过这些问题：
+
+- 刷朋友圈时，为什么几秒钟就能加载出几百张图片？
+- 查询订单时，为什么瞬间就能看到几个月前的数据？
+- 刷新短视频时，为什么视频几乎瞬间就能播放？
 
 这背后都有一个功臣：**缓存 (Cache)**。
 
-如果数据库是"仓库"，那缓存就是"柜台"。
-常用的商品（热数据）放在柜台上，随拿随用；不常用的商品才需要去仓库里找。
+### 0.1 什么是缓存？用生活化的例子理解
 
-### 0.1 为什么要缓存？
+想象一下你在家里的场景：
+
+**场景 1：没有缓存的日子**
+
+每次想喝水，你都要：
+1. 走到厨房（相当于访问数据库）
+2. 打开柜子
+3. 拿出水壶
+4. 倒水
+5. 回到客厅
+
+即使你一小时内要喝 10 次水，每次都要重复这个过程。很累对吧？
+
+**场景 2：有了缓存**
+
+你在客厅的茶几上放了一个水杯（这就是缓存！）：
+- 第一次喝水：你还是要去厨房倒水，但把水杯留在茶几上
+- 之后每次喝水：直接拿起茶几上的水杯喝就行
+
+**这就是缓存的核心思想**：把常用的东西放在触手可及的地方，避免每次都"跑远路"。
+
+回到计算机世界：
+
+| 生活中的例子 | 计算机中的对应 |
+| :--- | :--- |
+| **茶几上的水杯** | **内存缓存**（速度快，但容量小） |
+| **厨房的水壶** | **数据库**（速度慢，但容量大） |
+| **"我刚才用过这个水杯"** | **时间局部性**（刚用过的数据，很可能还会用） |
+| **"把这些常用的都放在茶几上"** | **空间局部性**（用过的数据附近的数据，也可能用到） |
+
+### 0.2 为什么要缓存？
 
 只有一个理由：**快**。
 
-| 存储介质         | 访问延迟 | 吞吐量 | 典型用途       |
-| :--------------- | :------- | :----- | :------------- |
-| **L1 CPU 缓存**  | ~1 ns    | 极高   | 寄存器、变量   |
-| **内存 (Redis)** | ~100 ns  | 高     | 热点数据、会话 |
-| **SSD 数据库**   | ~1 ms    | 中     | 持久化存储     |
-| **HDD 数据库**   | ~10 ms   | 低     | 归档存储       |
+但有多快呢？我们用个形象的比喻：
 
-**关键点**：缓存的本质是**用空间换时间**，通过在更快的存储介质中保留数据副本，减少访问慢速存储的次数。
+| 存储介质 | 访问时间 | 生活类比 | 能做什么 |
+| :--- | :--- | :--- | :--- |
+| **L1 CPU 缓存** | ~1 纳秒 | 眨一下眼睛（1/10秒）的 **十亿分之一** | CPU 执行一条指令 |
+| **内存 (Redis)** | ~100 纳秒 | 眨一下眼睛的 **千万分之一** | 存储热点数据 |
+| **SSD 数据库** | ~1 毫秒 | 眨一下眼睛 | 读写文件 |
+| **HDD 数据库** | ~10 毫秒 | 眨 10 下眼睛 | 传统硬盘操作 |
+
+**换个角度理解**：
+- 从内存读数据 = 从茶几拿水杯
+- 从 SSD 读数据 = 从厨房拿水壶
+- 从 HDD 读数据 = 从楼下便利店买水
+
+**关键点**：缓存的本质是**用空间换时间**——多准备几份"副本"放在快速的地方，节省每次都去"慢速地方"取数据的时间。
+
+### 0.3 缓存的真实案例
+
+**案例 1：淘宝商品详情页**
+
+当你打开一个商品页面时：
+- **商品基本信息**（价格、标题）：从 Redis 缓存读取（~5 毫秒）
+- **商品大图**：从 CDN 缓存读取（~20 毫秒）
+- **用户浏览历史**：从本地缓存读取（~1 毫秒）
+
+如果这些都不用缓存，全部查数据库：
+- 查询时间可能从 **5 毫秒** 变成 **200 毫秒**
+- 数据库要同时处理几百万人的请求，直接"累垮"
+
+**案例 2：微信朋友圈**
+
+你刷朋友圈时：
+- **图片**：之前看过的图片，都在手机本地缓存里
+- **好友列表**：第一次加载后缓存在内存里
+- **点赞数据**：热点数据在 Redis 缓存中
+
+没有缓存的话：每次刷新都要重新下载所有内容，流量和速度都受不了。
+
+---
+
+## 🗺️ 全局观：缓存知识地图
+
+在深入细节之前，让我们先看看缓存设计的"全貌"。就像旅游前先看地图一样，这样你不会迷路。
+
+### 核心目标（一句话概括）
+
+**让数据访问更快、系统更强，同时保证数据不出错。**
+
+### 知识体系地图
+
+```
+缓存设计
+│
+├─ 📦 基础概念（为什么需要缓存？）
+│   ├─ 局部性原理（时间局部性、空间局部性）
+│   ├─ 缓存生命周期（写入 → 命中 → 过期 → 淘汰）
+│   └─ 性能对比（内存 vs 数据库：快 100 倍）
+│
+├─ 🏗️ 架构选型（用什么缓存？）
+│   ├─ 本地缓存（单机快，但容量小）
+│   ├─ 分布式缓存（容量大，但稍慢）
+│   └─ 多级缓存（组合使用，最佳方案）
+│       ├─ 浏览器缓存（用户本地）
+│       ├─ CDN 缓存（离用户近）
+│       ├─ 应用本地缓存（极速）
+│       ├─ Redis 缓存（高容量）
+│       └─ 数据库（兜底）
+│
+├─ 🎯 设计模式（怎么用缓存？）
+│   ├─ Cache-Aside（最常用，手动控制）
+│   ├─ Read-Through（缓存自己加载）
+│   ├─ Write-Through（同步写缓存和数据库）
+│   └─ Write-Behind（异步写，最快但可能丢数据）
+│
+├─ ⚠️ 常见问题（缓存会出什么错？）
+│   ├─ 缓存穿透（查不存在数据，数据库压力大）
+│   ├─ 缓存击穿（热点数据过期，瞬间高并发）
+│   └─ 缓存雪崩（大量数据同时过期）
+│
+├─ 🔒 一致性保证（缓存和数据库不一致怎么办？）
+│   ├─ 更新策略（先更数据库，再删缓存）
+│   ├─ 延迟双删（极致一致性）
+│   └─ Binlog 订阅（异步解耦）
+│
+└─ 🛠️ 实战技巧（工程中怎么做？）
+    ├─ 布隆过滤器（快速判断数据是否存在）
+    ├─ 分布式锁（防止缓存击穿）
+    ├─ 随机 TTL（防止雪崩）
+    ├─ 缓存预热（启动时加载热点数据）
+    └─ 监控调优（命中率要 > 90%）
+```
+
+### 学习路径建议（0基础小白版）
+
+**第一步：理解核心概念**（1-2 天）
+- 理解"为什么需要缓存"（茶几 vs 厨房的例子）
+- 记住性能数据：内存比数据库快 100 倍
+- 了解缓存的生命周期（写入 → 命中 → 过期 → 淘汰）
+
+**第二步：掌握最常用的模式**（2-3 天）
+- 重点学习 **Cache-Aside 模式**（90% 的场景都用这个）
+- 动手写代码：用 Redis 做简单的键值缓存
+- 理解"为什么删缓存而不是更新缓存"
+
+**第三步：学习多级缓存**（3-5 天）
+- 理解为什么需要"多层防御"（浏览器 → CDN → 本地 → Redis → 数据库）
+- 掌握每一层的用途和特点
+- 动手实践：给自己的项目加一层缓存
+
+**第四步：解决常见问题**（1 周）
+- 理解缓存三大问题（穿透、击穿、雪崩）
+- 学习解决方案（布隆过滤器、分布式锁、随机 TTL）
+- 实战演练：模拟高并发场景，看缓存如何保护数据库
+
+**第五步：深入一致性**（1-2 周）
+- 理解缓存和数据库可能不一致的场景
+- 掌握"先更数据库，再删缓存"的最佳实践
+- 进阶：学习 Binlog 订阅方案
+
+**第六步：实战项目**（2-4 周）
+- 设计一个完整的缓存系统（如商品详情页缓存）
+- 搭建监控系统，实时查看缓存命中率
+- 压测验证：看看性能提升了多少倍
+
+### 关键指标（学完后你要能回答）
+
+- 缓存的**命中率**是多少？（优秀：> 90%）
+- 缓存能**提升多少性能**？（10-100 倍）
+- 如何解决缓存**三大问题**？（穿透、击穿、雪崩）
+- 缓存和数据库**不一致**怎么办？（先更库，再删缓存）
+- **多级缓存**的顺序是什么？（浏览器 → CDN → 本地 → Redis → 数据库）
 
 ---
 
diff --git a/docs/zh-cn/appendix/canvas-intro.md b/docs/zh-cn/appendix/canvas-intro.md
index 46b2937..fa8ca82 100644
--- a/docs/zh-cn/appendix/canvas-intro.md
+++ b/docs/zh-cn/appendix/canvas-intro.md
@@ -1,4 +1,4 @@
-# Canvas 2D 入门：从像素到动画 (Interactive Guide to Canvas)
+# Canvas 2D 入门：从像素到动画（交互式教程）
 
 > **学习指南**：本章节无需深厚的前端基础，通过交互式演示带你掌握 Canvas 2D 的核心原理和实践技巧。我们将从最基础的绘制开始，一直到构建复杂的交互式图形应用。
 
diff --git a/docs/zh-cn/appendix/context-engineering.md b/docs/zh-cn/appendix/context-engineering.md
index 02f7940..82aabb3 100644
--- a/docs/zh-cn/appendix/context-engineering.md
+++ b/docs/zh-cn/appendix/context-engineering.md
@@ -2,6 +2,13 @@
 
 > 💡 **学习指南**：如果说 Prompt Engineering 是教 AI "怎么说话"，那么 Context Engineering 就是教 AI "怎么记事"。本章节将通过一系列交互式实验，带你深入理解 AI 的记忆机制，从基础的滑动窗口到高级的 RAG 系统，掌握让 AI "过目不忘"的核心技术。
 
+在开始之前，建议你先了解两个概念：
+
+- **Token 是什么**：可以先阅读 [大语言模型入门](./llm-intro.md) 的「分词 & Token」部分。
+- **Prompt 是什么**：如果你还不熟悉 System / User / Assistant 的基本结构，可以先看 [提示词工程](./prompt-engineering.md)。
+
+<AgentContextFlow />
+
 ## 0. 引言：金鱼与大象
 
 想象一下，你正在和两个人聊天：
@@ -11,6 +18,13 @@
 
 **上下文工程 (Context Engineering)** 的目标，就是通过技术手段，让 AI 从 "金鱼" 进化成 "大象"。
 
+更具体地说：你每次调用模型时，都会把一份「输入包」发给它，这份输入包通常由这些部分拼起来：
+
+- **系统设定**（System Prompt）：角色、规则、边界。
+- **对话历史**（Messages）：你们之前聊过什么。
+- **工具结果**（Tool / Observation）：Agent 调用外部工具拿到的新信息。
+- **检索片段**（RAG Context）：从知识库临时取回的相关内容。
+
 但这里有一个核心挑战：**AI 的"脑容量"（上下文窗口）是有限的**。我们不能把全世界的信息都塞进去。
 
 我们需要解决五个核心问题：
@@ -31,7 +45,8 @@
 
 ### 1.2 实验：Token 与容量
 
-在 AI 的世界里，计量的单位不是"字"，而是 **Token**。一个 Token 大约相当于 0.75 个英文单词，或者 0.5-1 个汉字。
+在 AI 的世界里，计量的单位不是"字"，而是 **Token**。（Token 的更完整解释可以回看 [大语言模型入门](./llm-intro.md)。）
+粗略地说，一个 Token 大约相当于 0.75 个英文单词，或 0.5-1 个汉字（会因内容而变化）。
 
 试着在下面的模拟器中输入文字，看看它是如何填满上下文窗口的：
 
@@ -39,9 +54,14 @@
 
 **关键点**：
 
-- **溢出即丢失**：一旦超过红色警戒线，模型不仅会报错，或者会直接截断后面的内容。
+- **溢出即丢失**：一旦超过红色警戒线，模型可能会报错，或者直接截断后面的内容。
 - **昂贵的记忆**：上下文越长，推理速度越慢，费用也越高。
 
+### 1.3 额外收益：前缀稳定与缓存命中
+
+在 Agent 场景里，上下文通常是「系统设定 + 工具定义 + 历史消息 + 本轮新信息」的拼接。
+如果你能让这份输入包的**前半段尽量稳定**（比如系统提示、工具列表不要频繁变动），很多模型/服务会更容易复用缓存，从而降低延迟与成本。
+
 ---
 
 ## 2. 第二步：即时记忆 (Sliding Window)
diff --git a/docs/zh-cn/appendix/git-intro.md b/docs/zh-cn/appendix/git-intro.md
index 994aafb..fa9fe63 100644
--- a/docs/zh-cn/appendix/git-intro.md
+++ b/docs/zh-cn/appendix/git-intro.md
@@ -2,6 +2,14 @@
 
 > 💡 **一句话解释**：Git 就是代码世界的**游戏存档管理器**。它能让你随时“读档”重来，也能让你和队友在各自的“平行宇宙”里互不干扰地开发。
 
+> ✅ **安全说明**：本页所有交互组件都是“模拟器”，不会对你电脑上的真实 Git 仓库执行任何操作；但真实项目里建议严格按步骤来，不要依赖“自动下一步”。
+
+## 0. 最常用的 5 个场景（直接照抄）
+
+如果你只想“立刻能用”，先把这块过一遍：每个场景都是现实工作中最常见的 Git 流程。
+
+<GitScenariosDemo />
+
 ## 1. 为什么我们需要它？
 
 你是否经历过这种绝望？
diff --git a/docs/zh-cn/appendix/llm-intro.md b/docs/zh-cn/appendix/llm-intro.md
index 5c6e129..87296a4 100644
--- a/docs/zh-cn/appendix/llm-intro.md
+++ b/docs/zh-cn/appendix/llm-intro.md
@@ -107,24 +107,95 @@
 
 ---
 
+## 3.5 插播：到底什么是“模型”？
+
+在讲具体的架构之前，我们先通俗地理解一下“模型”这个词。
+
+在 AI 领域，**模型（Model）** 其实就是一个超级复杂的**函数**或者**黑盒子**。
+
+- **输入**：一堆数字（比如上面的 Token ID）。
+- **处理**：黑盒子里有亿万个参数（可以理解为亿万个调节旋钮），它们会对输入数据进行疯狂的加减乘除运算。
+- **输出**：另一堆数字（代表预测结果，比如下一个词的概率）。
+
+**打个比方：**
+
+你可以把模型想象成一位**经验丰富的老厨师**：
+1.  **输入（食材）**：你给他牛肉、土豆、番茄。
+2.  **模型（厨师的脑子）**：他根据自己学过的成千上万道菜谱（训练数据），在脑子里快速计算：牛肉切块、土豆去皮、火候控制...
+3.  **输出（菜肴）**：最后端出一盘土豆炖牛腩。
+
+所谓的**训练（Training）**，就是让这位厨师从学徒做起，让他试错亿万次。做咸了就调一下“盐旋钮”，做淡了就调一下“火候旋钮”，直到他能稳定做出美味的菜肴。
+
+现在的 LLM，就是一位“读过全人类书本”的超级厨师，只不过他炒的不是菜，而是文字。
+
 ## 4. 进化之路：从 RNN 到 Transformer
 
-现在我们有了**高效的数据表达**（矩阵），接下来需要一个**高效的机器**（模型）来处理它。
+有了数据（Token），有了厨师（模型），接下来要看这位厨师是怎么思考的。
 
-### 4.1 为什么要淘汰 RNN？
+在 AI 进化史上，主要有两种“思考方式”（架构）：**RNN** 和 **Transformer**。
 
-以前的模型（RNN）像人读书一样，**从左到右**一个字一个字读。
+### 4.1 以前的笨办法：RNN（传话游戏）
 
-- **缺点1：慢**。必须读完第1个字才能读第2个，没法并行（浪费了矩阵并行的优势）。
-- **缺点2：忘**。读到文章最后，可能已经忘了开头讲什么了（长距离遗忘）。
+早期的模型（RNN，循环神经网络）处理一句话时，就像我们在玩**传话游戏**。
 
-### 4.2 Transformer 强在哪？
+**工作方式：**
+1.  读第 1 个词“我”，记在脑子里，传给第 2 步。
+2.  读第 2 个词“喜欢”，结合刚才的记忆，更新一下脑子里的信息，再传给第 3 步。
+3.  读第 3 个词“吃”，再更新记忆...
+4.  ...直到读完最后一个词。
 
-现在的 LLM 都基于 Transformer 架构，它完美契合了矩阵并行的特性：
+**这就带来了两个致命缺点：**
 
-1.  **并行阅读**：它可以**一眼看完**整句话，不用一个字一个字读。
-2.  **注意力机制 (Attention)**：它可以让句子里的每一个词，都**直接关注**到其他所有词。
-    - 比如读到“它”这个字时，模型能瞬间注意到前面的“小猫”，从而知道“它”指代的是猫。
+1.  **慢（无法并行）**：必须等上一个人传完话，下一个人才能开始。没法让 100 个人同时干活。
+2.  **忘（长距离遗忘）**：传话传到第 100 个人时，他可能早就忘了第 1 个人说的是“我”还是“你”。这就导致模型写长文章时，容易前言不搭后语。
+
+### 4.2 现在的天才设计：Transformer（圆桌会议）
+
+2017 年，Google 提出了一种全新的架构——**Transformer**。它彻底改变了规则，把“传话游戏”变成了**圆桌会议**。
+
+**工作方式：**
+Transformer 不再一个接一个地传话，而是让**所有词一次性全部坐上桌**。
+
+1.  **上帝视角（并行计算）**：所有词同时进场，不用排队。大家把自己的信息写在纸上，摊在桌子中间。
+2.  **注意力机制（Attention）**：这是它的杀手锏。每个词都可以**直接**去看桌上其他任何一个词的信息。
+    - 比如读到“它”这个字时，模型不需要回忆前面的传话，而是直接一眼看到前面的“小猫”，瞬间明白“它 = 小猫”。
+
+**这就完美解决了 RNN 的痛点：**
+
+*   **快**：大家同时看资料，GPU 可以火力全开，效率极高。
+*   **不忘**：不管句子多长，第 1 个词和第 10000 个词的距离都是“一步之遥”，想看谁就看谁。
+
+> **总结一下**：
+> *   **RNN**：像走迷宫，一步一步摸索，容易迷路。
+> *   **Transformer**：像开上帝视角看地图，终点起点尽收眼底。
+
+#### 为什么还需要“位置”信息？
+
+因为 Transformer 是“一锅端”，如果不做特殊处理，它分不清“我爱你”和“你爱我”的区别（词都一样，只是顺序不同）。
+所以我们会给每个词贴个**号码牌（位置编码）**，告诉模型谁在第 1 位，谁在第 2 位。
+
+> 小提醒：很多 LLM 是自回归（预测下一个词）的，所以在生成时仍然是一 token 一 token 往外吐；但在**每一步生成**的内部计算里，Transformer 依旧更能利用矩阵并行与缓存优化。
+
+### 4.3 效率黑科技：KV 缓存 (KV Cache)
+
+你可能听说过，生成长文本时，越到后面越慢，或者显存占用越大。这通常是因为模型需要“记住”之前生成的所有内容。
+
+**Transformer 怎么“记笔记”？**
+
+在 Transformer 的注意力机制中，每个词都会生成 `Key (K)` 和 `Value (V)` 两个向量，用来供后面的词“查询”。
+
+- 当模型生成第 100 个词时，它需要回头看前 99 个词的 K 和 V。
+- 如果每次都重新计算前 99 个词的 K 和 V，那就太浪费了！
+
+**KV Cache 的作用：**
+
+KV Cache 就像是一个**“增量笔记本”**。
+
+1.  **不重算**：算完第 1 个词的 K 和 V，存起来。
+2.  **只算新**：生成第 2 个词时，只计算第 2 个词的 K 和 V，然后和第 1 个词的 K、V 拼在一起。
+3.  **越存越多**：随着对话进行，这个“笔记本”（显存占用）会越来越厚。
+
+这就是为什么长文本对话（Long Context）会消耗大量显存的原因——**不是模型变大了，而是笔记（KV Cache）太厚了。**
 
 <RNNvsTransformer />
 
diff --git a/docs/zh-cn/appendix/queue-design.md b/docs/zh-cn/appendix/queue-design.md
index fb27d7b..f6849f0 100644
--- a/docs/zh-cn/appendix/queue-design.md
+++ b/docs/zh-cn/appendix/queue-design.md
@@ -6,26 +6,245 @@
 
 ## 0. 引言：系统的"缓冲器"
 
-你在淘宝买完东西，为什么点击"支付"后，不会立刻收到短信通知？
-你在抖音发了一条评论，为什么点赞数不是瞬间就增加？
+### 0.1 从生活中的例子说起
 
-这背后都有一个功臣：**消息队列 (Message Queue)**。
+想象一下这个场景：
 
-如果同步调用是"打电话"，那消息队列就是"发微信"。
-打电话要求对方**立即响应**（同步），发微信可以等对方**稍后处理**（异步）。
+**🏪 餐厅点餐的智慧**
 
-### 0.1 为什么要用消息队列？
+你走进一家繁忙的餐厅，前台服务员（A）迅速给你点单、收钱，然后告诉你"请稍等，餐好了会叫号"。你不需要站在厨房门口等着厨师（B）直接把菜端给你，而是可以安心坐下刷手机。
 
-只有一个理由：**解耦和削峰**。
+**为什么这么做？**
+- 如果每个顾客都站在厨房门口等（同步调用），厨房会乱成一团
+- 用"叫号系统"（消息队列），服务员快速完成点餐，厨房按自己的节奏做菜
+- 即使厨师临时休息了，点餐也不会受影响，订单会排队等他回来
 
-- **解耦**：A 不需要直接调用 B，把消息扔给队列就完事了。
-  - _例子_：用户下单后，订单服务不需要直接调用库存、积分、通知服务，而是发一条"下单成功"消息。
-- **削峰**：把瞬间的高峰流量"摊平"，避免系统被打爆。
-  - _例子_：秒杀活动，1 秒内有 10 万个请求，但数据库只能处理 1000 个。队列把这 10 万个请求暂存起来，慢慢处理。
+**🛒 淘宝支付的秘密**
+
+你在淘宝买完东西，点击"支付"后，系统显示"支付成功"，但你可能要等几秒甚至几分钟才收到短信通知。
+
+**为什么不是立即收到？**
+因为支付系统要做的事情太多了：
+- ✅ 扣款（必须立即完成）
+- ⏳ 发送短信通知（可以稍后）
+- ⏳ 更新积分（可以稍后）
+- ⏳ 给推荐系统发送数据（可以稍后）
+
+如果把所有事情都卡在"支付"这个按钮上，你可能要等 5 秒才能看到"支付成功"。聪明的系统会：
+1. 先完成扣款
+2. 把其他任务扔进一个"待办事项池"（消息队列）
+3. 立即告诉你"支付成功"
+4. 后台慢慢处理那些待办事项
+
+**这就是消息队列的核心价值：把"必须现在做"和"可以稍后做"的事情分开。**
+
+### 0.2 什么是消息队列？
+
+**消息队列**就像一个智能的"中转站"或"缓冲区"：
+
+```
+如果同步调用是"打电话"（要求对方立即响应）
+那消息队列就是"发微信"（可以等对方稍后处理）
+```
+
+**用一个比喻理解**：
+
+> **没有消息队列**：你直接把文件交给同事，他正在开会，你只能干等。
+>
+> **有消息队列**：你把文件放到他的办公桌（队列），继续做自己的事。他开完会自己来拿。
+
+### 0.3 为什么要用消息队列？
+
+核心原因就两个：**解耦**和**削峰**。
+
+#### 📌 解耦：让系统更灵活
+
+**问题**：A 直接调用 B，一旦 B 出问题，A 也跟着完蛋。
+
+```python
+# 紧耦合的例子（不好）
+def create_order(user_id, product_id):
+    order = db.save_order(user_id, product_id)
+
+    # 如果通知服务挂了，整个订单创建就失败
+    notification.send_sms(user_id, "订单创建成功")
+    notification.send_email(user_id, "订单创建成功")
+
+    return order
+```
+
+**解决**：用消息队列做"中介"，A 只管发消息，不关心 B 是否在线。
+
+```python
+# 松耦合的例子（好）
+def create_order(user_id, product_id):
+    order = db.save_order(user_id, product_id)
+
+    # 扔到队列里就完事了，不管通知服务是否在线
+    queue.publish("order.created", {
+        "user_id": user_id,
+        "order_id": order.id
+    })
+
+    return order
+```
+
+**好处**：
+- ✅ 订单系统不依赖通知系统
+- ✅ 可以随时增加新的消费者（比如加一个"积分系统"）
+- ✅ 通知系统升级不影响订单系统
+
+#### 📌 削峰：把洪峰变成平缓的水流
+
+**问题**：瞬间流量太高，系统扛不住。
+
+**场景**：双11秒杀
+- 1 秒内有 10 万个请求涌进来
+- 数据库每秒只能处理 1000 个
+- 如果直接打到数据库，数据库会直接"爆掉"
+
+**解决**：用消息队列当"蓄水池"
+
+```
+洪水来了（10 万请求/秒）
+    ↓
+[大坝] 消息队列暂存
+    ↓
+平缓流出（1000 请求/秒）
+    ↓
+[农田] 数据库慢慢处理
+```
 
 <PeakShavingDemo />
 
-**关键点**：消息队列的本质是**异步通信**，通过把"立即执行"变成"稍后处理"，提升系统的吞吐量和可用性。
+### 0.4 消息队列的本质
+
+**一句话总结**：消息队列的本质是**异步通信**，通过把"立即执行"变成"稍后处理"，提升系统的吞吐量和可用性。
+
+**关键特点**：
+- ✅ **异步**：不需要等任务完成，立即返回
+- ✅ **解耦**：服务之间不直接依赖
+- ✅ **缓冲**：暂存消息，平滑流量
+- ✅ **可靠**：消息持久化，不怕丢失
+
+---
+
+## 🗺️ 全局观：消息队列知识地图
+
+### 消息队列的核心价值
+
+> **用"空间换时间，用异步换性能"** —— 让系统可以"快速响应请求，慢慢处理任务"
+
+### 知识体系地图
+
+```
+消息队列知识体系
+│
+├── 📦 基础概念（必学）
+│   ├── 生产者（Producer）：发送消息的一方
+│   ├── 消费者（Consumer）：接收并处理消息的一方
+│   ├── 消息代理（Broker）：存储和转发消息的中介
+│   └── 消息模式
+│       ├── 点对点（P2P）：一条消息被一个消费者消费
+│       └── 发布订阅（Pub/Sub）：一条消息被多个消费者消费
+│
+├── 🎯 核心应用场景（必学）
+│   ├── 异步处理：把同步改成异步，提升响应速度
+│   ├── 削峰填谷：缓冲高峰流量，保护系统
+│   ├── 系统解耦：消除服务之间的直接依赖
+│   └── 数据分发：一条消息分发给多个消费者
+│
+├── 🔒 可靠性保证（重要）
+│   ├── 消息不丢失：持久化 + ACK 机制 + 多副本
+│   ├── 消息不重复：幂等性设计
+│   └── 消息顺序：单分区或内存排序
+│
+├── 🚀 高级特性（进阶）
+│   ├── 死信队列（DLQ）：处理无法消费的消息
+│   ├── 延迟消息：指定时间后才消费
+│   └── 事务消息：保证本地事务和消息发送的一致性
+│
+├── 🛠️ 主流消息队列（了解）
+│   ├── RabbitMQ：传统消息队列，功能丰富
+│   ├── Kafka：分布式日志系统，吞吐量极大
+│   ├── RocketMQ：电商级消息队列，功能全面
+│   └── Redis Stream：轻量级队列，适合小规模应用
+│
+└── 📊 实战设计（综合应用）
+    └── 秒杀系统、订单系统、异步任务处理
+```
+
+### 学习路径建议（0 基础小白）
+
+#### 🎒 第一阶段：建立直觉（1-2 小时）
+**目标**：理解消息队列是什么，为什么需要它
+
+1. **阅读本章节的 0. 引言部分**
+   - 理解"餐厅点餐"和"淘宝支付"的例子
+   - 掌握"解耦"和"削峰"两个核心价值
+
+2. **动手体验**（可选）
+   - 找一个生活中的"队列"例子（如餐厅叫号、客服排队）
+   - 画出它的流程图
+
+#### 📚 第二阶段：掌握基础（1-2 天）
+**目标**：理解核心概念和基本用法
+
+1. **学习基础概念**
+   - 生产者、消费者、Broker
+   - 点对点 vs 发布订阅
+   - 阅读本章节第 1 部分
+
+2. **选择一个消息队列上手**
+   - 推荐从 **Redis Stream** 或 **RabbitMQ** 开始（学习曲线低）
+   - 跟着官方文档写一个"生产者-消费者"的 Hello World
+
+3. **实现第一个异步任务**
+   - 场景：用户注册后，异步发送欢迎邮件
+   - 用代码实现：注册接口 → 发消息到队列 → 消费者发送邮件
+
+#### 🔥 第三阶段：深入核心（1 周）
+**目标**：掌握消息队列的核心用法
+
+1. **学习核心设计模式**
+   - 异步处理：提升响应速度
+   - 削峰填谷：保护系统
+   - 系统解耦：降低依赖
+   - 阅读本章节第 3 部分
+
+2. **保证可靠性**
+   - 消息不丢失：持久化 + ACK
+   - 消息不重复：幂等性设计
+   - 阅读本章节第 4 部分
+
+3. **实战练习**
+   - 设计一个"秒杀系统"：用消息队列削峰
+   - 设计一个"订单系统"：用消息队列解耦
+
+#### 🚀 第四阶段：精通高级特性（2-4 周）
+**目标**：处理复杂场景
+
+1. **高级特性**
+   - 死信队列：处理异常消息
+   - 延迟消息：定时任务
+   - 事务消息：保证一致性
+   - 阅读本章节第 5 部分
+
+2. **完整系统设计**
+   - 设计一个带监控的异步处理系统
+   - 处理各种异常场景（消息丢失、重复、顺序错乱）
+
+3. **深入学习特定 MQ**
+   - Kafka：学习高可用架构（多副本、分区）
+   - RocketMQ：学习事务消息
+
+### 学习建议
+
+- ✅ **先理解，再动手**：不要一开始就陷入代码细节，先理解为什么需要消息队列
+- ✅ **从简单开始**：不要一上来就学 Kafka，从 Redis Stream 或 RabbitMQ 开始
+- ✅ **边学边练**：每学一个概念，就写代码实践一下
+- ✅ **关注应用场景**：不仅要知其然，还要知其所以然
+- ✅ **阅读真实案例**：看看淘宝、抖音等大厂如何使用消息队列
 
 ---