Skip to content

Commit 77a891a

Browse files
tt-a1itt-a1i
committed
feat: 添加术语表和Prompt处理管道动画页面
新增术语表页面(Glossary)和Prompt处理管道动画页面(PromptProcessingPipelineAnimation)，并更新导航配置和页面懒加载逻辑。同时为多个现有页面添加介绍性内容组件，提升文档可读性和用户体验。
1 parent 773a17e commit 77a891a

15 files changed

Lines changed: 4743 additions & 15 deletions

‎src/App.tsx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import { StartHere } from './pages/StartHere';
99
import { Overview } from './pages/Overview';
1010

1111
// 懒加载的页面
12+
const Glossary = lazy(() => import('./pages/Glossary'));
1213
const EndToEndWalkthrough = lazy(() => import('./pages/EndToEndWalkthrough').then(m => ({ default: m.EndToEndWalkthrough })));
1314
const UpstreamDiffOverview = lazy(() => import('./pages/UpstreamDiffOverview').then(m => ({ default: m.UpstreamDiffOverview })));
1415
const StartupFlow = lazy(() => import('./pages/StartupFlow').then(m => ({ default: m.StartupFlow })));
@@ -18,8 +19,10 @@ const AuthenticationFlow = lazy(() => import('./pages/AuthenticationFlow').then(
1819
const RequestLifecycle = lazy(() => import('./pages/RequestLifecycle').then(m => ({ default: m.RequestLifecycle })));
1920
const InteractionLoop = lazy(() => import('./pages/InteractionLoop').then(m => ({ default: m.InteractionLoop })));
2021
const GeminiChatCore = lazy(() => import('./pages/GeminiChatCore').then(m => ({ default: m.GeminiChatCore })));
22+
const ServicesArchitecture = lazy(() => import('./pages/ServicesArchitecture').then(m => ({ default: m.ServicesArchitecture })));
2123
const SystemPromptArch = lazy(() => import('./pages/SystemPromptArch').then(m => ({ default: m.SystemPromptArch })));
2224
const ContentGeneratorDetails = lazy(() => import('./pages/ContentGeneratorDetails').then(m => ({ default: m.ContentGeneratorDetails })));
25+
const MultiProviderArchitecture = lazy(() => import('./pages/MultiProviderArchitecture').then(m => ({ default: m.MultiProviderArchitecture })));
2326
const VisionModelSwitch = lazy(() => import('./pages/VisionModelSwitch').then(m => ({ default: m.VisionModelSwitch })));
2427
const MemoryManagement = lazy(() => import('./pages/MemoryManagement').then(m => ({ default: m.MemoryManagement })));
2528
const ToolReference = lazy(() => import('./pages/ToolReference').then(m => ({ default: m.ToolReference })));
@@ -100,6 +103,8 @@ const LruCacheAnimation = lazy(() => import('./pages/LruCacheAnimation'));
100103
const PtyLifecycleAnimation = lazy(() => import('./pages/PtyLifecycleAnimation'));
101104
const StreamingJsonParserAnimation = lazy(() => import('./pages/StreamingJsonParserAnimation'));
102105
const VimCompositeActionsAnimation = lazy(() => import('./pages/VimCompositeActionsAnimation'));
106+
const PromptProcessingPipelineAnimation = lazy(() => import('./pages/PromptProcessingPipelineAnimation'));
107+
const SlashCommandExecutionAnimation = lazy(() => import('./pages/SlashCommandExecutionAnimation'));
103108
const CoreCode = lazy(() => import('./pages/CoreCode').then(m => ({ default: m.CoreCode })));
104109
const LoopMechanism = lazy(() => import('./pages/LoopMechanism').then(m => ({ default: m.LoopMechanism })));
105110

@@ -194,6 +199,8 @@ function App() {
194199
return <UpstreamDiffOverview />;
195200
case 'overview':
196201
return <Overview />;
202+
case 'glossary':
203+
return <Glossary onNavigate={(tab) => navigateToTab(tab)} />;
197204
case 'startup':
198205
return <StartupFlow />;
199206
case 'startup-chain':
@@ -208,10 +215,14 @@ function App() {
208215
return <InteractionLoop />;
209216
case 'gemini-chat':
210217
return <GeminiChatCore />;
218+
case 'services-arch':
219+
return <ServicesArchitecture />;
211220
case 'system-prompt':
212221
return <SystemPromptArch />;
213222
case 'content-gen':
214223
return <ContentGeneratorDetails />;
224+
case 'multi-provider':
225+
return <MultiProviderArchitecture />;
215226
case 'vlm-switch':
216227
return <VisionModelSwitch />;
217228
case 'memory':
@@ -272,6 +283,8 @@ function App() {
272283
return <TelemetrySystem />;
273284
case 'animation':
274285
return <Animation />;
286+
case 'slash-cmd-exec-anim':
287+
return <SlashCommandExecutionAnimation />;
275288
case 'tool-scheduler-anim':
276289
return <ToolSchedulerAnimation />;
277290
case 'streaming-parser-anim':
@@ -372,6 +385,8 @@ function App() {
372385
return <StreamingJsonParserAnimation />;
373386
case 'vim-composite-actions-anim':
374387
return <VimCompositeActionsAnimation />;
388+
case 'prompt-pipeline-anim':
389+
return <PromptProcessingPipelineAnimation />;
375390
case 'code':
376391
return <CoreCode />;
377392
case 'loop':

‎src/nav.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ export const navGroups: NavGroup[] = [
2121
items: [
2222
{ id: 'start-here', label: 'Start Here', highlight: true },
2323
{ id: 'overview', label: '架构概览' },
24+
{ id: 'glossary', label: '术语表' },
2425
],
2526
},
2627
{
@@ -33,8 +34,10 @@ export const navGroups: NavGroup[] = [
3334
{ id: 'lifecycle', label: '请求生命周期', highlight: true },
3435
{ id: 'interaction-loop', label: '交互主循环', highlight: true },
3536
{ id: 'gemini-chat', label: '核心循环' },
37+
{ id: 'services-arch', label: '服务层架构', highlight: true },
3638
{ id: 'system-prompt', label: 'Prompt构建' },
3739
{ id: 'content-gen', label: 'API调用层' },
40+
{ id: 'multi-provider', label: '多厂商架构', highlight: true },
3841
{ id: 'vlm-switch', label: 'VLM切换' },
3942
{ id: 'memory', label: '上下文管理' },
4043
],
@@ -121,6 +124,7 @@ export const navGroups: NavGroup[] = [
121124
defaultOpen: false,
122125
items: [
123126
{ id: 'animation', label: '完整流程动画', highlight: true },
127+
{ id: 'slash-cmd-exec-anim', label: '斜杠命令执行', highlight: true },
124128
{ id: 'tool-scheduler-anim', label: '工具调度状态机', highlight: true },
125129
{ id: 'streaming-parser-anim', label: '流式解析器', highlight: true },
126130
{ id: 'mcp-discovery-anim', label: 'MCP服务发现', highlight: true },
@@ -179,6 +183,7 @@ export const navGroups: NavGroup[] = [
179183
{ id: 'pty-lifecycle-anim', label: 'PTY 生命周期', highlight: true },
180184
{ id: 'streaming-json-parser-anim', label: '流式 JSON 解析', highlight: true },
181185
{ id: 'vim-composite-actions-anim', label: 'Vim 复合操作', highlight: true },
186+
{ id: 'prompt-pipeline-anim', label: 'Prompt 处理管道', highlight: true },
182187
],
183188
},
184189
{

‎src/pages/ErrorHandling.tsx‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,110 @@
1+
import { useState } from 'react';
12
import { HighlightBox } from '../components/HighlightBox';
23
import { MermaidDiagram } from '../components/MermaidDiagram';
34
import { CodeBlock } from '../components/CodeBlock';
45

6+
function Introduction({
7+
isExpanded,
8+
onToggle,
9+
}: {
10+
isExpanded: boolean;
11+
onToggle: () => void;
12+
}) {
13+
return (
14+
<div className="mb-8 bg-gradient-to-r from-[var(--terminal-green)]/10 to-[var(--cyber-blue)]/10 rounded-xl border border-[var(--border-subtle)] overflow-hidden">
15+
<button
16+
onClick={onToggle}
17+
className="w-full px-6 py-4 flex items-center justify-between hover:bg-white/5 transition-colors"
18+
>
19+
<div className="flex items-center gap-3">
20+
<span className="text-2xl">🛡️</span>
21+
<span className="text-xl font-bold text-[var(--text-primary)]">
22+
错误处理导读
23+
</span>
24+
</div>
25+
<span
26+
className={`transform transition-transform text-[var(--text-muted)] ${isExpanded ? 'rotate-180' : ''}`}
27+
>
28+
▼
29+
</span>
30+
</button>
31+
32+
{isExpanded && (
33+
<div className="px-6 pb-6 space-y-4">
34+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--terminal-green)]">
35+
<h4 className="text-[var(--terminal-green)] font-bold mb-2">
36+
🎯 错误处理目标
37+
</h4>
38+
<p className="text-[var(--text-secondary)] text-sm">
39+
CLI 的错误处理系统旨在：<strong>分类错误</strong>（可恢复 vs 不可恢复）、
40+
<strong>尝试恢复</strong>（重试、回退）、<strong>优雅降级</strong>（用户通知、日志记录）。
41+
</p>
42+
</div>
43+
44+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--amber)]">
45+
<h4 className="text-[var(--amber)] font-bold mb-2">
46+
🔧 错误类型层次
47+
</h4>
48+
<div className="grid grid-cols-2 md:grid-cols-4 gap-2 mt-2">
49+
<div className="bg-[var(--bg-card)] p-2 rounded text-center">
50+
<div className="text-xs text-[var(--terminal-green)]">CLIError</div>
51+
<div className="text-[10px] text-[var(--text-muted)]">基础类</div>
52+
</div>
53+
<div className="bg-[var(--bg-card)] p-2 rounded text-center">
54+
<div className="text-xs text-[var(--cyber-blue)]">APIError</div>
55+
<div className="text-[10px] text-[var(--text-muted)]">网络错误</div>
56+
</div>
57+
<div className="bg-[var(--bg-card)] p-2 rounded text-center">
58+
<div className="text-xs text-[var(--amber)]">ToolError</div>
59+
<div className="text-[10px] text-[var(--text-muted)]">工具失败</div>
60+
</div>
61+
<div className="bg-[var(--bg-card)] p-2 rounded text-center">
62+
<div className="text-xs text-[var(--purple)]">AuthError</div>
63+
<div className="text-[10px] text-[var(--text-muted)]">认证失败</div>
64+
</div>
65+
</div>
66+
</div>
67+
68+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--cyber-blue)]">
69+
<h4 className="text-[var(--cyber-blue)] font-bold mb-2">
70+
🔄 可恢复错误
71+
</h4>
72+
<ul className="text-[var(--text-secondary)] text-sm space-y-1">
73+
<li>• <strong>429 Rate Limit</strong> - 等待后重试</li>
74+
<li>• <strong>500/502/503/504</strong> - 服务端临时错误，可重试</li>
75+
<li>• <strong>工具执行失败</strong> - 通常可重试或回退</li>
76+
</ul>
77+
</div>
78+
79+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--purple)]">
80+
<h4 className="text-[var(--purple)] font-bold mb-2">📊 关键数字</h4>
81+
<div className="grid grid-cols-2 md:grid-cols-4 gap-3">
82+
<div className="text-center">
83+
<div className="text-xl font-bold text-[var(--terminal-green)]">6+</div>
84+
<div className="text-xs text-[var(--text-muted)]">错误类型</div>
85+
</div>
86+
<div className="text-center">
87+
<div className="text-xl font-bold text-[var(--cyber-blue)]">3</div>
88+
<div className="text-xs text-[var(--text-muted)]">最大重试</div>
89+
</div>
90+
<div className="text-center">
91+
<div className="text-xl font-bold text-[var(--amber)]">指数</div>
92+
<div className="text-xs text-[var(--text-muted)]">退避策略</div>
93+
</div>
94+
<div className="text-center">
95+
<div className="text-xl font-bold text-[var(--purple)]">✓</div>
96+
<div className="text-xs text-[var(--text-muted)]">遥测集成</div>
97+
</div>
98+
</div>
99+
</div>
100+
</div>
101+
)}
102+
</div>
103+
);
104+
}
105+
5106
export function ErrorHandling() {
107+
const [isIntroExpanded, setIsIntroExpanded] = useState(true);
6108
const errorFlowChart = `flowchart TD
7109
start["错误发生"]
8110
capture["错误捕获<br/>Error Boundary"]
@@ -554,6 +656,11 @@ function attemptJSONFix(
554656

555657
return (
556658
<div className="space-y-8">
659+
<Introduction
660+
isExpanded={isIntroExpanded}
661+
onToggle={() => setIsIntroExpanded(!isIntroExpanded)}
662+
/>
663+
557664
{/* 概述 */}
558665
<section>
559666
<h2 className="text-2xl font-bold text-cyan-400 mb-4">错误处理系统</h2>

‎src/pages/GeminiChatCore.tsx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,100 @@
1+
import { useState } from 'react';
12
import { Layer } from '../components/Layer';
23
import { HighlightBox } from '../components/HighlightBox';
34
import { CodeBlock } from '../components/CodeBlock';
45
import { JsonBlock } from '../components/JsonBlock';
56

7+
function Introduction({ isExpanded, onToggle }: { isExpanded: boolean; onToggle: () => void }) {
8+
return (
9+
<div className="mb-8 bg-gradient-to-r from-[var(--cyber-blue)]/10 to-[var(--terminal-green)]/10 rounded-xl border border-[var(--border-subtle)] overflow-hidden">
10+
<button
11+
onClick={onToggle}
12+
className="w-full px-6 py-4 flex items-center justify-between hover:bg-white/5 transition-colors"
13+
>
14+
<div className="flex items-center gap-3">
15+
<span className="text-2xl">🔄</span>
16+
<span className="text-xl font-bold text-[var(--text-primary)]">核心概念介绍</span>
17+
</div>
18+
<span className={`transform transition-transform text-[var(--text-muted)] ${isExpanded ? 'rotate-180' : ''}`}>▼</span>
19+
</button>
20+
21+
{isExpanded && (
22+
<div className="px-6 pb-6 space-y-4">
23+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--cyber-blue)]">
24+
<h4 className="text-[var(--cyber-blue)] font-bold mb-2">🎯 核心概念</h4>
25+
<p className="text-[var(--text-secondary)] text-sm">
26+
GeminiChat 是整个 CLI 的"大脑"，负责管理与 AI 模型的所有通信。
27+
它实现了关键的 <strong className="text-[var(--terminal-green)]">Continuation 机制</strong>：当 AI 需要执行工具时，
28+
自动将结果反馈并继续对话，形成 用户→AI→工具→AI→... 的循环。
29+
</p>
30+
</div>
31+
32+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--amber)]">
33+
<h4 className="text-[var(--amber)] font-bold mb-2">🔧 为什么这样设计</h4>
34+
<p className="text-[var(--text-secondary)] text-sm">
35+
AI Agent 需要自主决策何时完成任务。通过 <code className="text-[var(--amber)] bg-[var(--amber)]/10 px-1 rounded">finish_reason</code> 判断：
36+
STOP 表示任务完成，TOOL_USE 表示需要执行工具后继续。这让 AI 可以连续执行多个操作直到任务真正完成。
37+
</p>
38+
</div>
39+
40+
<div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--terminal-green)]">
41+
<h4 className="text-[var(--terminal-green)] font-bold mb-2">🏗️ 核心流程</h4>
42+
<div className="grid grid-cols-1 md:grid-cols-4 gap-3 mt-2">
43+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--cyber-blue)]/30 text-center">
44+
<div className="text-[var(--cyber-blue)] font-semibold text-sm">1. sendMessage</div>
45+
<div className="text-xs text-[var(--text-muted)] mt-1">发送用户消息</div>
46+
</div>
47+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--terminal-green)]/30 text-center">
48+
<div className="text-[var(--terminal-green)] font-semibold text-sm">2. Stream</div>
49+
<div className="text-xs text-[var(--text-muted)] mt-1">流式接收响应</div>
50+
</div>
51+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--amber)]/30 text-center">
52+
<div className="text-[var(--amber)] font-semibold text-sm">3. Tool Call</div>
53+
<div className="text-xs text-[var(--text-muted)] mt-1">执行工具调用</div>
54+
</div>
55+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--purple)]/30 text-center">
56+
<div className="text-[var(--purple)] font-semibold text-sm">4. Continue?</div>
57+
<div className="text-xs text-[var(--text-muted)] mt-1">判断是否继续</div>
58+
</div>
59+
</div>
60+
</div>
61+
62+
<div className="grid grid-cols-2 md:grid-cols-4 gap-3 text-center">
63+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--border-subtle)]">
64+
<div className="text-xl font-bold text-[var(--terminal-green)]">100</div>
65+
<div className="text-xs text-[var(--text-muted)]">最大轮次</div>
66+
</div>
67+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--border-subtle)]">
68+
<div className="text-xl font-bold text-[var(--amber)]">3</div>
69+
<div className="text-xs text-[var(--text-muted)]">重试次数</div>
70+
</div>
71+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--border-subtle)]">
72+
<div className="text-xl font-bold text-[var(--cyber-blue)]">13</div>
73+
<div className="text-xs text-[var(--text-muted)]">事件类型</div>
74+
</div>
75+
<div className="bg-[var(--bg-card)] p-3 rounded border border-[var(--border-subtle)]">
76+
<div className="text-xl font-bold text-[var(--purple)]">∞</div>
77+
<div className="text-xs text-[var(--text-muted)]">Continuation</div>
78+
</div>
79+
</div>
80+
81+
<div className="text-xs text-[var(--text-muted)] bg-[var(--bg-card)] px-3 py-2 rounded flex items-center gap-2">
82+
<span>📁</span>
83+
<code>packages/core/src/core/geminiChat.ts</code>
84+
</div>
85+
</div>
86+
)}
87+
</div>
88+
);
89+
}
90+
691
export function GeminiChatCore() {
92+
const [isIntroExpanded, setIsIntroExpanded] = useState(true);
93+
794
return (
895
<div>
96+
<Introduction isExpanded={isIntroExpanded} onToggle={() => setIsIntroExpanded(!isIntroExpanded)} />
97+
998
<h2 className="text-2xl text-cyan-400 mb-5">GeminiChat 核心循环机制</h2>
1099

11100
{/* 核心概念 */}

0 commit comments

Comments
 (0)