v0.3.1: Web Agent 基础之前后端基本原理&示例

tutorial/web_basics/README.md

@@ -0,0 +1,35 @@
+# FastAPI + HTML 入门示例
+
+这个目录是一个独立的教程示例，不依赖主项目中的 `main.py` 和 `static/` 目录。
+
+## 启动服务
+
+在项目根目录执行：
+
+```bash
+python -m uvicorn tutorial.web_basics.main:app --reload
+```
+
+如果当前 Python 不支持带连字符的模块路径，可以先进入本目录再启动：
+
+```bash
+cd tutorial/web-basics
+python -m uvicorn main:app --reload
+```
+
+然后打开浏览器访问：
+
+```text
+http://127.0.0.1:8000
+```
+
+`index.html` 保持和教程中的代码一致：点击“发送”后，页面内的 JavaScript 会直接将输入内容转换为大写并更新标题。`main.py` 中的 FastAPI 接口用于配合教程后续讲解 HTTP 请求和前后端分离。
+
+## 目录说明
+
+```text
+web_basics/
+├── README.md
+├── index.html  # 前端页面：HTML、CSS 和 JavaScript
+└── main.py     # 后端接口：FastAPI 和 POST /
+```

tutorial/web_basics/index.html

@@ -0,0 +1,88 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Welcome Page</title>
+
+    <style>
+      /* CSS 负责网页的外观：字体、对齐方式、间距和颜色。 */
+      body {
+        font-family: sans-serif;
+        text-align: center;
+      }
+
+      /* 设置输入框的内边距、边框和圆角。 */
+      input {
+        padding: 8px;
+        border: 1px solid #ccc;
+        border-radius: 6px;
+      }
+
+      /* 设置发送按钮的大小、颜色和鼠标样式。 */
+      button {
+        padding: 8px 16px;
+        border: 0;
+        border-radius: 6px;
+        color: white;
+        background: #4e9af5;
+        cursor: pointer;
+      }
+
+      /* 给标题增加渐变色和动画效果，和交互逻辑无关。 */
+      h1 {
+        margin-bottom: 24px;
+        background: linear-gradient(90deg, #ff4d6d, #ff9f1c, #2ec4b6, #4361ee, #b5179e);
+        background-size: 300% auto;
+        color: transparent;
+        font-size: 56px;
+        font-weight: 800;
+        letter-spacing: 2px;
+        -webkit-background-clip: text;
+        background-clip: text;
+        text-shadow: 0 4px 16px rgba(67, 97, 238, 0.2);
+        animation: gradient-flow 5s linear infinite;
+      }
+
+      @keyframes gradient-flow {
+        to {
+          background-position: 300% center;
+        }
+      }
+
+    </style>
+  </head>
+
+  <body>
+    <!-- HTML 负责搭建页面结构：标题、输入框和按钮。 -->
+    <div>
+      <!-- JavaScript 会根据 id 找到并修改这个标题。 -->
+      <h1 id="title">Hello World</h1>
+
+      <!-- 用户在输入框中填写要处理的内容。 -->
+      <input id="content" type="text" placeholder="输入内容" />
+      <!-- 点击按钮后，下面的 JavaScript 逻辑会被触发。 -->
+      <button id="send-button" type="button">发送</button>
+    </div>
+
+    <script>
+      // 先找到页面中需要操作的三个元素。
+      const title = document.querySelector("#title");
+      const content = document.querySelector("#content");
+      const sendButton = document.querySelector("#send-button");
+
+      // 监听按钮点击：读取输入，转成大写，再更新标题。
+      sendButton.addEventListener("click", () => {
+        const value = content.value.trim();
+
+        // 输入为空时不更新页面。
+        if (!value) {
+          return;
+        }
+
+        // 将输入内容转换成大写，并显示在标题中。
+        title.textContent = value.toUpperCase();
+      });
+    </script>
+  </body>
+</html>

tutorial/web_basics/main.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+
+BASE_DIR = Path(__file__).parent
+app = FastAPI()
+
+
+# 请求体：定义客户端提交的数据结构
+class InputData(BaseModel):
+    value: str
+
+
+@app.get("/")
+def get_page() -> FileResponse:
+    """返回前端页面。"""
+    return FileResponse(BASE_DIR / "index.html")
+
+
+@app.post("/")
+def process_data(request: InputData) -> dict[str, str]:
+    """将输入全部大写，然后返回给客户端。"""
+    result = request.value.strip().upper()
+
+    # 返回结果：将处理后的数据封装成字典，也称为响应体。
+    return {
+        "result": result,
+    }