教程编写

Author: leonlucc

.github/workflows/deploy-mdbook.yml

@@ -24,6 +24,12 @@ jobs:
         with:
           mdbook-version: 'latest'
 
+      # 安装二进制安装器并下载 mdbook-mermaid
+      - name: Install mdbook-mermaid
+        run: |
+          curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
+          cargo binstall -y mdbook-mermaid
+
       - name: Build mdBook
         run: mdbook build book/   # 假设 book.toml 位于 book/ 目录
 

.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 .vscode/
 .idea/
 .trae/
+.obsidian/
 
 # tmp
 tmp/

README.md

@@ -4,6 +4,8 @@
 
 Tiny Agent 遵循**由浅入深、循序渐进**的设计理念，不依赖复杂框架，从一次最简单的大模型调用开始，逐步构建出一个具备知识、工具、推理、记忆和协作能力的智能体。适合已掌握 Python 基础、想掌握AI Agent底层原理的开发者。
 
+![](./book/src/images/snapshot-v0.2.gif)
+
 ## 项目特点
 
 * 🚀 极简轻量化实现：剔除冗余封装，代码注释完整，单文件模块易阅读、逐行可拆解学习

book/book.toml

@@ -2,3 +2,13 @@
 title = "极简智能体：AI Agent 渐进式开发实战"
 authors = ["leon"]
 language = "cn"
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output]
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

book/mermaid-init.js

@@ -0,0 +1,39 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();

book/mermaid.min.js

@@ -6,7 +6,7 @@
 # 第一部分：模型基础与全栈通信（基础篇）
 
 - [第一章：Hello LLM（你好，大模型）](./chapter_01.md)
-- [第二章：Streaming Web（流式 Web 输出）](./chapter_02.md)
+- [第二章：Streaming Web（Web 流式输出）](./chapter_02.md)
 
 
 # 附录

book/src/SUMMARY.md

@@ -1,6 +1,6 @@
 # 第一章：Hello LLM（你好，大模型）
 
-> **导语**：本章是 Tiny Agent 的起点，不用前端、不做多轮历史，只先跑通“用户输入一句话，大模型回复一句话”的最小闭环。
+> **导语**：本章是 Tiny Agent 的起点，不用前端、不做多轮历史，只先跑通“用户输入一句话，大模型回复一句话”的最小闭环。完成本章后，你将掌握大模型的 API 调用方式，为 Agent 开发奠定基础。
 >
 > **源码版本**：[v0.1](https://github.com/leonlucc/tiny-agent/tree/v0.1)
 
@@ -42,7 +42,7 @@ AI: 你好，我是一个可以理解和生成文本的 AI 助手。
 3. 把用户输入包装成一条 `user` 消息，调用 `client.chat.completions.create()`。
 4. 从响应中取出 `response.choices[0].message.content` 并打印到终端。
 
-本版本没有 Web UI、没有多轮对话，它只解决一个问题：**确认代码能够真正访问 LLM，并拿到一次回复**。
+这个版本没有 Web UI、没有多轮对话，它只做一件事：**验证代码能成功调用LLM并获取回复**。
 ```mermaid
 flowchart LR
     User[CLI 终端<br/>用户输入/输出] -->|输入| App[Python 应用<br/>simple_call.py]
@@ -168,10 +168,13 @@ LLM_API_KEY=your_api_key_here
 LLM_BASE_URL=https://api.deepseek.com
 LLM_MODEL=deepseek-v4-flash
 ```
-安全提醒：`.env` 文件包含 API Key 等敏感信息，切记将其加入 .gitignore，避免意外提交到版本控制系统。
+> **💡 小贴士：安全提醒**
+>
+> `.env` 文件包含 API Key 等敏感信息，切记将其加入 .gitignore，避免意外提交到版本控制系统。
 
-💡 小贴士：如何快速获取 API Key？
->本项目兼容标准的 OpenAI 协议，国内外的诸多主流平台都可以无缝接入。推荐注册并使用国内极速且高性价比的平台，例如 [DeepSeek](https://platform.deepseek.com/) 或 [硅基流动](https://siliconflow.cn/) 等 API 聚合服务。注册获取 `sk-...` 格式的密钥后，直接填入 .env 即可无缝运行。
+> **💡 小贴士：如何快速获取 API Key？**
+>
+> 本项目兼容标准的 OpenAI 协议，国内外的诸多主流平台都可以无缝接入。推荐注册并使用国内极速且高性价比的平台，例如 [DeepSeek](https://platform.deepseek.com/) 或 [硅基流动](https://siliconflow.cn/) 等 API 聚合服务。注册获取 `sk-...` 格式的密钥后，直接填入 .env 即可无缝运行。
 
 
 ### 4.4 运行入口
@@ -310,7 +313,7 @@ def main() -> None:
 
 ## 5. Git Diff 导读
 
-本版本相对于空工程，核心变化是新增 `backend` 目录，上文已经详细讲解，完整代码已提交至 GitHub 仓库，你可以切换到 `v0.0.1` Tag查看或直接运行 `git checkout v0.0.1`查看。
+本版本相对于空工程，核心变化是新增 `backend` 目录，上文已经详细讲解，完整代码已提交至 GitHub 仓库，你可以切换到 `v0.1` Tag查看或直接运行 `git checkout v0.1`查看。
 
 ---
 
@@ -365,7 +368,7 @@ messages=[{"role": "user", "content": message}]
 
 ### 6.7 为什么错误处理非常简单？
 
-v0.0.1 的目标是跑通闭环，不是建立完整的错误分类体系。
+本章的目标是跑通闭环，不是建立完整的错误分类体系。
 
 因此代码只做两类处理：
 
@@ -390,6 +393,6 @@ v0.0.1 的目标是跑通闭环，不是建立完整的错误分类体系。
 
 ---
 
-下一章，我们会在这个基础上引入 Chat History，让 Tiny Agent 从“一问一答”走向“连续对话”。
+下一章，我们会在这个基础上引入 Web 流式输出，让 Tiny Agent 从一问一答的命令行，走向逐字呈现的浏览器。
 
-[→ 进入第二章：Chat（基础对话）](./chapter_02.md)
+[→ 进入第二章：Streaming Web（Web 流式输出）](./chapter_02.md)