工程模板说明 — HelloMeng

本文来自《AI 应用开发课程》月份 1 课程文档，已整理为网站文章版本。

1. 模板目标

本模板用于统一月份 1 各练习项目的工程结构，避免你在每个项目里重新思考目录设计。

2. 推荐目录结构

project/
├── app/
│   ├── __init__.py
│   ├── config.py
│   ├── logger.py
│   ├── models.py
│   ├── clients/
│   │   └── llm_client.py
│   ├── services/
│   │   └── chat_service.py
│   └── tools/
│       └── registry.py
├── tests/
│   ├── test_config.py
│   └── test_models.py
├── .env.example
├── README.md
└── pyproject.toml

3. 各目录职责

app/config.py 负责配置读取和配置对象构建。
app/logger.py 负责日志初始化。
app/models.py 负责 Pydantic 模型与基础类型。
app/clients/ 负责外部 API 调用封装。
app/services/ 负责核心业务逻辑。
app/tools/ 负责工具定义、注册和执行。
tests/ 负责测试。

4. 核心边界规则

入口层只做输入输出，不做业务逻辑。
外部 API 封装单独放 clients。
工具调用相关逻辑单独放 tools。
能测试的逻辑尽量不要放在入口文件。

5. 本月统一模型建议

至少包含：

ChatMessage
ChatRequest
ChatResponse
ToolDefinition
ToolCallResult
ErrorResponse

6. 为什么这个模板适合月份 1

因为它已经提前为后面的内容留好了位置：

第 2 周可以往 clients 增加 DeepSeek 调用
第 2 周可以往 tools 增加 Tool Calling
第 3 周可以复用 services 接入 FastAPI
第 4 周可以在保留核心逻辑的前提下同时接 CLI 与 API

7. 你应该什么时候偏离这个模板

当前月份不建议偏离。因为你现在最需要的是稳定结构，而不是设计自由度。

如果后续月份 3 或月份 4 出现更复杂的模块拆分，再调整也不迟。

8. 为什么这个模板对月份 1 特别合适

它的关键价值，不是“目录长得像大厂项目”，而是让你在学习阶段就提前体验到边界感：

哪些文件属于配置层
哪些文件属于业务层
哪些文件属于外部依赖调用
哪些文件属于工具能力

这会让后面的每一章都更容易放到正确位置。

9. 一个最常见的错误用法

很多人虽然照着建了目录，但实际写代码时仍然会：

把核心逻辑写回 main.py
把所有函数塞进 utils.py
把模型调用和业务判断写在一个文件里

这说明“目录存在”不等于“边界形成”。你需要持续用这个模板来检查自己的代码是否真的按职责放置。