HelloMeng
← Back to 文字
AI 应用开发课程 · 月份 1 · 综合项目：研发助手

项目需求与架构

Published2025.10.03 Words 1,390 Reading ~ 5 min

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

学习目标

学完本节后，你应当能够：

  • 明确月份 1 综合项目的边界。
  • 理解为什么项目必须是“小而真实”的研发助手。
  • 画出 CLI + FastAPI 双入口共用核心逻辑的架构。

前置知识

  • 已完成月份 1 前面所有模块

1. 项目目标

本项目名称建议为：rd-assistant

本项目要解决的最小问题是：

  • 接收研发相关文本输入
  • 调用模型进行分析或生成
  • 在需要时执行工具
  • 提供 CLI 和 FastAPI 两种使用入口

2. 推荐功能范围

本月只做以下 3 个核心功能中的 1-2 个即可：

  • 根据 diff 生成 commit message
  • 从需求描述中抽取待办项
  • 总结错误日志并给出排查步骤

不要把它做成“万能开发平台”。

3. 非目标

以下内容明确不属于月份 1 范围：

  • 向量数据库
  • RAG
  • LangGraph Agent
  • 前端页面
  • 多用户系统

4. 架构图

flowchart TD
    A["CLI 入口"] --> C["核心 Service 层"]
    B["FastAPI 入口"] --> C
    C --> D["LLM Client"]
    C --> E["Tool Registry / Executor"]
    D --> F["DeepSeek API"]

5. 推荐目录结构

rd-assistant/
├── app/
│   ├── api/
│   ├── cli/
│   ├── clients/
│   ├── services/
│   ├── tools/
│   ├── config.py
│   ├── logger.py
│   └── models.py
├── tests/
├── README.md
├── .env.example
└── pyproject.toml

6. 统一接口约定

项目中至少保留这些对象：

  • ChatMessage
  • ChatRequest
  • ChatResponse
  • ToolDefinition
  • ToolCallResult
  • ErrorResponse

LLM client 至少保留这些方法：

  • generate()
  • stream()
  • structured_generate()
  • call_with_tools()

7. 验收目标

项目完成后，必须满足：

  • 至少一个真实有用工作流跑通
  • CLI 与 API 复用同一套核心服务
  • 有日志
  • 有最小成本或调用统计
  • README 可指导他人跑起项目

8. 实操任务

  1. 决定本项目的 1-2 个核心功能
  2. 画出自己的简化架构图
  3. 确认目录结构
  4. 写出第一版 README 提纲

9. 自测题

  1. 为什么月份 1 项目必须“小而真实”？
  2. 为什么 CLI 和 FastAPI 必须共用核心逻辑？
  3. 为什么本月项目不应该继续扩功能而忽视结构？

10. 这个项目为什么叫“研发助手”

因为它必须同时满足两个条件：

  • 对你当前背景足够贴近
  • 能自然串起月份 1 所有基础能力

相比“通用聊天机器人”这种过于宽泛的题目，研发助手更适合月份 1，原因在于：

  • 任务边界容易定义
  • 工具场景自然存在
  • CLI 入口合理
  • FastAPI 服务化合理
  • 后续接 RAG 和 Agent 也合理

11. 本项目和前面所有模块的映射关系

你应该明确知道：前面学的每个模块，都会在这里落地。

月份 1 模块在综合项目中的落点
Python 基础项目所有基础代码可读可写
工程化目录、配置、日志、测试
LLM APIllm_client.py
Tool Callingtools/ 与 tool_service.py
FastAPIapp/api 与 app/main.py
LangChain可选用于某条链路的组件化重构

这张表很重要，因为它能帮助你理解：综合项目不是“另起炉灶”，而是“把前面学到的东西装配起来”。

12. 为什么项目范围必须克制

初学者在做综合项目时最容易犯的错误，不是“不会做”，而是“想做太多”。一旦你在月份 1 项目里同时想做：

  • 前端
  • RAG
  • Agent
  • 多用户
  • 复杂权限

几乎必然会把基础能力打散。

月份 1 项目真正要验证的是：

  • 你能否把一条主链路做清楚
  • 你能否让结构和边界站得住

而不是“你能否一次性做出最终产品”。

13. 一个推荐的功能组合

对于月份 1，最推荐的组合是这两个：

  1. 从需求描述中抽取待办项
  2. 根据 diff 或变更说明生成 commit message

原因：

  • 都和研发场景直接相关
  • 一个偏结构化输出
  • 一个偏自然语言生成
  • 都可以自然接工具调用

14. 从空目录到最小项目的阶段式构建

不要把项目理解成“一次写完最终结构”。更稳的方式是按阶段推进：

阶段一：项目壳子

  • uv init
  • .env.example
  • README.md
  • app/、tests/

阶段二：模型能力

  • llm_client.py
  • models.py
  • chat_service.py

阶段三：工具能力

  • tools/definitions.py
  • tools/registry.py
  • tools/executor.py
  • tool_service.py

阶段四：双入口

  • cli/main.py
  • api/routes.py
  • main.py

阶段五：补展示能力

  • 日志
  • 调用记录
  • README
  • 录屏说明

15. 一个更完整的项目骨架说明

rd-assistant/
├── app/
│   ├── api/
│   │   └── routes.py
│   ├── cli/
│   │   └── main.py
│   ├── clients/
│   │   └── llm_client.py
│   ├── services/
│   │   ├── chat_service.py
│   │   └── tool_service.py
│   ├── tools/
│   │   ├── definitions.py
│   │   ├── registry.py
│   │   └── executor.py
│   ├── config.py
│   ├── logger.py
│   ├── main.py
│   └── models.py
├── tests/
├── README.md
├── .env.example
└── pyproject.toml

这套结构的最大价值不在于“标准”，而在于它能非常清楚地映射职责边界。

16. 本章完成后你应该具备的能力

完成本章后，你应当做到：

  1. 能解释综合项目为什么选研发助手。
  2. 能说明前面各模块如何汇总到这个项目。
  3. 能用阶段式方式理解项目搭建，而不是只看最终目录。

17. 如果你卡在这里，先回看哪几章

  • 项目工程骨架不稳：回看 02-Python工程化基础/
  • Tool Calling 不稳：回看 04-Tool_Calling基础/
  • FastAPI 分层不稳：回看 05-FastAPI服务化基础/

18. 从本章过渡到下一章的桥接说明

接下来进入 02-CLI入口实现.md。

这是综合项目最合理的第一入口，因为 CLI 最轻、最快，也最适合先验证核心业务层是否真的清晰可复用。

✦ Fin ✦