企业官网建设流程全解析

• 示例工程

本文围绕仓库中 week5/README.md 展开，讲解这套面向自主编码 Agent（autonomous coding agents）实验的极简全栈起手应用：后端基于 FastAPI + SQLite（SQLAlchemy），前端为无需 Node 工具链的静态页面，配套 pytest 最小测试集、black + ruff 格式化和预提交钩子，以及一套供 Agent 驱动的开发任务清单。读完本文，你将掌握该项目的完整启动流程、目录结构与配置方式，理解后端启动、建表与种子数据注入的底层实现，并能在此基础上直接开展 Agent 工作流（含 Warp 多 Agent 协作）的实验。

项目定位：为 Agent 实验而生的最小全栈 Starter

按 week5/README.md 的说明，这是一个 minimal full‑stack starter，核心目标是让开发者（或开发 Agent）拥有一个足够小、足够清晰、可快速重置的“实验场”，其技术选型刻意保持克制：

• FastAPI 后端 + SQLite（SQLAlchemy ORM）：无需独立数据库服务，单文件 SQLite 即可持久化；
• 静态前端：由 FastAPI 直接托管，不需要 Node 工具链即可运行；
• 最小测试集（pytest）：覆盖核心 API 行为，方便 Agent 验证改动；
• Pre-commit（black + ruff）：保持代码风格一致，减少 Agent 引入的格式噪声；
• 任务清单（Tasks）：见 week5/docs/TASKS.md，用于练习 Agent 驱动的工作流。

配套的 week5/assignment.md 进一步说明了它的用途：作为 Warp Agentic Development Environment 与多 Agent 工作流的 playground，实验范围被严格限定在week5/内的 backend、frontend、logic 与 tests。

快速开始（Quickstart）

README 给出了三步起手流程，其中虚拟环境创建可选用venv或conda两种方式。

方式一：venv（README 默认示例）

cd /path/to/modern-software-dev-assignments python -m venv .venv && source .venv/bin/activate pip install -e .[dev]

注：README 中的cd路径是作者本机路径（/Users/mihaileric/...），请替换为你克隆仓库后的实际根目录。

方式二：conda（assignment.md 示例）

conda activate cs146s

安装可编辑依赖-e .[dev]会依据仓库根目录的 pyproject.toml 安装运行时依赖与 dev 依赖（测试、格式化等工具）。

（可选）安装 pre-commit 钩子：

pre-commit install

钩子配置位于 week5/pre-commit-config.yaml，包含 black（24.4.2）、ruff（v0.4.8，带--fix）、end-of-file-fixer 与 trailing-whitespace 四个钩子。

启动应用（须在week5/目录下）：

cd week5 && make run

启动成功后：

• http://localhost:8000—— 前端页面；
• http://localhost:8000/docs—— FastAPI 自动生成的交互式 API 文档（OpenAPI/Swagger UI）。

目录结构

week5/ ├── backend/ # FastAPI 应用 ├── frontend/ # 由 FastAPI 托管的静态 UI ├── data/ # SQLite 数据库 + 种子数据 ├── docs/ # 供 Agent 驱动工作流使用的 TASKS ├── Makefile # run / test / format / lint / seed 等目标 └── pre-commit-config.yaml # black + ruff 预提交钩子

后端内部再细分为路由与业务层：backend/app/routers/存放notes.py与action_items.py两个路由模块，backend/app/services/extract.py存放从文本提取 Action Item 的纯逻辑函数，backend/app/models.py、schemas.py、db.py分别负责 ORM 模型、Pydantic 校验模型与数据库会话管理。

后端实现速览：启动、建表与种子数据

从 week5/backend/app/main.py 的源码可以看到应用的装配方式：

• FastAPI(title="Modern Software Dev Starter (Week 5)")创建应用实例；
• 启动时先确保data/目录存在（Path("data").mkdir(...)）；
• app.mount("/static", StaticFiles(directory="frontend"))将前端静态资源挂载到/static；
• GET /直接返回frontend/index.html；
• startup_event()中执行Base.metadata.create_all(bind=engine)建表，随后调用apply_seed_if_needed()注入种子数据；
• 最后include_router挂载 notes 与 action_items 两个路由。

数据库会话管理位于 week5/backend/app/db.py：通过load_dotenv()读取.env，默认数据库路径取自环境变量DATABASE_PATH（默认./data/app.db），SQLite 引擎配置了check_same_thread=False以兼容 FastAPI 的线程模型。apply_seed_if_needed()的逻辑值得注意：仅在数据库文件首次创建时执行 week5/data/seed.sql，其中预置了notes与action_items两张表的建表语句及示例数据（例如 Welcome 笔记和 "Try pre-commit" 行动项），因此删除本地app.db即可重置实验环境。

ORM 模型定义在 week5/backend/app/models.py：Note（id、title、content）与ActionItem（id、description、completed）两张表；对应 Pydantic 模型见 week5/backend/app/schemas.py。路由层（如 week5/backend/app/routers/notes.py）当前提供笔记的列表、创建、搜索与单条查询，其中搜索使用 SQLAlchemy 的contains实现标题/内容的子串匹配，搜索词为空时退化为全量列表——这也是 week5/docs/TASKS.md 中“分页与排序搜索”任务的改造起点。

测试

在week5/目录下运行：

cd week5 && make test

对应 week5/Makefile 中的PYTHONPATH=. pytest -q backend/tests，测试集位于backend/tests/（含test_notes.py、test_action_items.py、test_extract.py等）。测试直接针对后端 API 与提取逻辑，是 Agent 改动后快速回归的主要手段。

格式化与 Lint

cd week5 && make format cd week5 && make lint

• make format执行black .并随后ruff check . --fix自动修复；
• make lint仅执行ruff check .做静态检查。

这两个命令与 pre-commit 钩子（black + ruff）保持一致，是保证 Agent 产出代码风格统一的关键。

配置

README 说明：将week5/下的.env.example复制为.env即可覆盖默认配置，最典型的是数据库路径。例如：

cd week5 && cp .env.example .env

DATABASE_PATH=./data/app.db

该变量会被 week5/backend/app/db.py 中的os.getenv("DATABASE_PATH", "./data/app.db")读取；修改它即可将数据库迁移到其他位置。同理，make run支持通过HOST/PORT环境变量覆盖监听地址与端口（默认127.0.0.1:8000），方便多实例并行实验。

为 Agent 驱动工作流准备的任务清单

README 强调项目包含“Tasks to practice agent-driven workflows”，任务清单即 week5/docs/TASKS.md。该文件按难度划分了 11 项任务，覆盖前后端与测试的典型改造场景，例如：

• 前端迁移 Vite + React（复杂）：替换静态资源为构建产物，FastAPI 挂载dist并新增web-install、web-dev、web-build等 Make 目标；
• 笔记搜索分页排序（中）：实现GET /notes/search?q=...&page=1&page_size=10&sort=...，返回items/total/page/page_size结构；
• 完整笔记 CRUD 与乐观更新（中）：新增PUT/DELETE /notes/{id}，前端做乐观状态更新与错误回滚；
• Action items 过滤与批量完成（中）：GET /action-items?completed=...与事务化的POST /action-items/bulk-complete；
• 标签多对多关系（复杂）：Tag模型与note_tags关联表，配合#hashtags自动提取；
• 提取逻辑增强（中）：扩展 week5/backend/app/services/extract.py（当前仅支持以!结尾或todo:开头的行），支持#hashtags与- [ ] task text语法，并新增POST /notes/{id}/extract；
• 统一错误响应封装（易–中）：全局异常处理器输出{ "ok": false, "error": { "code": "...", "message": "..." } }风格 JSON；
• 列表分页、索引、测试覆盖率、Vercel 部署等其余任务。

这些任务与 week5/assignment.md 的要求相互呼应：实现任务时必须同时利用 Warp Drive（保存的 prompts、rules 或 MCP 服务器）与 Warp 内的多 Agent 工作流（例如在不同 Warp 标签页并发处理独立任务，并可用git worktree避免 Agent 之间互相覆盖改动），最终在writeup.md中记录每个自动化的设计、前后对比、自主级别与多 Agent 协作经验。

小结

Week 5 起手项目刻意保持“最小”，却覆盖了全栈应用的关键构件：FastAPI 路由与静态托管、SQLAlchemy + SQLite 持久化、种子数据、pytest 测试与 black/ruff 规范。理解 week5/README.md 中的启动、测试、格式化与配置流程，再对照 week5/Makefile 与 week5/backend/app/main.py 等源码，你就能把整套工具链交给 Agent：让它在有限范围内自主改代码、跑测试、过 lint，并借此练习保存 Prompt、规则与多 Agent 并发的现代开发工作流。

• 示例工程