AI编程 实战案例分享｜附配置文件

本文将通过一个真实可落地的实战案例，分享如何使用 AI 辅助完成一个“智能周报生成系统”的开发过程。文章不仅介绍需求分析、架构设计、核心代码思路，还会附上常用配置文件示例，帮助你快速复用到自己的项目中。

一、为什么要做 AI 编程实战？

过去我们写代码，通常依赖搜索引擎、技术文档、博客文章和个人经验。现在，AI 编程助手已经逐渐成为开发流程中的重要工具。它不仅能帮我们生成代码，还能参与需求拆解、架构设计、测试用例编写、异常排查、配置优化和文档整理。

但很多人使用 AI 编程时容易停留在“让 AI 写一段函数”的阶段，真正落地项目时却发现问题很多，比如：

• AI 生成的代码不符合项目规范；
• 业务上下文缺失，导致代码不能直接运行；
• 配置文件缺失，环境搭建困难；
• 缺少异常处理和日志记录；
• 生成结果不稳定，不利于长期维护；
• 项目结构混乱，后续扩展成本高。

因此，本文不只是展示“AI 写代码”，而是完整分享一个可实践的开发案例：如何借助 AI 从 0 到 1 搭建一个智能周报生成系统。

二、案例背景：智能周报生成系统

很多团队都有写周报的习惯。开发人员每周需要整理完成事项、遇到的问题、下周计划等内容。如果团队成员较多，管理者还需要汇总大家的周报，提炼项目进度和风险点。

传统方式通常是人工整理，存在几个痛点：

1. 重复劳动多：每周都要手动组织语言；
2. 信息分散：任务可能来自 Git 提交、项目管理平台、聊天记录等；
3. 格式不统一：不同人的表达风格不一致；
4. 管理者汇总困难：难以快速发现重点、风险和延期事项；
5. 历史追踪不方便：周报数据没有结构化存储。

于是我们设计一个 AI 周报生成系统，目标是：

• 支持用户输入本周工作内容；
• 自动生成结构化周报；
• 支持按模板输出；
• 支持调用大模型接口；
• 支持保存历史记录；
• 提供后端 API，方便后续接入前端或企业微信、飞书等平台。

三、技术选型

本案例采用轻量化技术栈，适合个人项目、中小型团队内部工具或 AI 编程学习项目。

1. 后端框架

选择 FastAPI。

原因：

• 启动速度快；
• 原生支持 OpenAPI 文档；
• 类型提示友好；
• 适合构建 AI 应用 API；
• 与 Pydantic 配合方便做参数校验。

2. 数据存储

选择 SQLite 作为演示数据库。

原因：

• 无需额外安装数据库服务；
• 适合本地开发和小型工具；
• 方便迁移到 MySQL、PostgreSQL。

3. AI 模型接口

系统预留统一的 LLM 调用层，可以对接不同模型服务，例如：

• OpenAI API；
• 通义千问；
• 智谱 AI；
• DeepSeek；
• 私有化部署的大模型接口。

为了通用，本文用伪 OpenAI 兼容接口作为示例。

4. 项目管理

使用：

• python-dotenv 管理环境变量；
• pydantic-settings 管理配置；
• loguru 管理日志；
• SQLAlchemy 管理数据库；
• uvicorn 启动服务。

四、项目目录结构

推荐的项目结构如下：

ai-weekly-report/
├── app/
│   ├── api/
│   │   └── report.py
│   ├── core/
│   │   ├── config.py
│   │   └── logger.py
│   ├── db/
│   │   ├── database.py
│   │   └── models.py
│   ├── schemas/
│   │   └── report.py
│   ├── services/
│   │   ├── llm_service.py
│   │   └── report_service.py
│   └── main.py
├── logs/
├── .env
├── requirements.txt
├── README.md
└── docker-compose.yml

这样的结构有几个好处：

• api 层只负责接口定义；
• service 层处理业务逻辑；
• db 层处理数据库连接和模型；
• schemas 层负责请求和响应结构；
• core 层放配置、日志等通用能力；
• 后续扩展任务系统、用户系统、权限系统都比较方便。

五、AI 编程的正确使用方式

在实际开发中，不建议直接对 AI 说：

帮我写一个周报系统。

这样得到的结果往往很泛，项目结构也可能不稳定。

更推荐的做法是分阶段给 AI 下指令。

阶段一：让 AI 帮你拆需求

可以这样提问：

我想开发一个 AI 周报生成系统，后端使用 FastAPI，数据库使用 SQLite，
需要支持用户输入工作内容，调用大模型生成结构化周报，并保存历史记录。
请帮我拆分功能模块、设计接口和数据库表。

AI 通常会输出：

• 功能模块；
• 数据库表；
• API 接口；
• 项目结构；
• 核心业务流程。

我们再根据实际情况筛选和调整。

阶段二：让 AI 生成项目骨架

请根据上述设计，生成 FastAPI 项目目录结构，并分别说明每个文件的作用。
要求分层清晰，适合后续扩展。

这一步能帮助我们快速建立项目雏形。

阶段三：逐文件生成代码

不要一次性让 AI 输出所有文件，否则容易出现上下文混乱。更好的方式是：

请先生成 app/core/config.py，要求使用 pydantic-settings 读取 .env 配置。

然后继续：

请生成 app/db/database.py 和 app/db/models.py，使用 SQLAlchemy 定义周报表。

逐步推进，代码质量会更高，也更容易检查。

阶段四：让 AI 做代码审查

代码生成后，可以继续让 AI 扮演审查者：

请以高级 Python 后端工程师的角度审查以下代码，
重点检查异常处理、可维护性、安全性和扩展性。

这一步非常重要。AI 不仅能写代码，也能帮助你发现潜在问题。

六、核心配置文件

下面给出本项目常用配置文件，方便直接参考。

1. .env 配置文件

APP_NAME=AI Weekly Report
APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8000

DATABASE_URL=sqlite:///./weekly_report.db

LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://api.example.com/v1
LLM_MODEL=deepseek-chat
LLM_TIMEOUT=60

LOG_LEVEL=INFO

说明：

• APP_ENV 用于区分开发、测试、生产环境；
• DATABASE_URL 为数据库连接地址；
• LLM_API_KEY 不建议写死在代码中；
• LLM_BASE_URL 支持替换为不同模型厂商地址；
• LLM_MODEL 可根据实际模型名称修改；
• LOG_LEVEL 控制日志输出级别。

2. requirements.txt

fastapi==0.115.0
uvicorn==0.30.6
SQLAlchemy==2.0.34
pydantic==2.8.2
pydantic-settings==2.4.0
python-dotenv==1.0.1
httpx==0.27.2
loguru==0.7.2

安装依赖：

pip install -r requirements.txt

3. app/core/config.py

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    APP_NAME: str = "AI Weekly Report"
    APP_ENV: str = "development"
    APP_HOST: str = "0.0.0.0"
    APP_PORT: int = 8000

    DATABASE_URL: str = "sqlite:///./weekly_report.db"

    LLM_API_KEY: str
    LLM_BASE_URL: str
    LLM_MODEL: str = "deepseek-chat"
    LLM_TIMEOUT: int = 60

    LOG_LEVEL: str = "INFO"

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


settings = Settings()

这个文件的作用是统一管理项目配置。后续代码中只需要引入 settings，就可以读取环境变量。

4. app/core/logger.py

import sys
from loguru import logger
from app.core.config import settings


logger.remove()

logger.add(
    sys.stdout,
    level=settings.LOG_LEVEL,
    format="{time:YYYY-MM-DD HH:mm:ss} | "
           "{level} | "
           "{name}:{function}:{line} - "
           "{message}",
)

logger.add(
    "logs/app.log",
    rotation="10 MB",
    retention="7 days",
    compression="zip",
    level=settings.LOG_LEVEL,
    encoding="utf-8",
)

app_logger = logger

日志配置建议在项目早期就加上，否则后期排查 AI 调用异常、接口超时、数据库错误会比较困难。

七、数据库模型设计

周报系统核心表可以先设计得简单一些：

字段包括：

• id：主键；
• user_name：用户名；
• raw_content：用户输入的原始内容；
• generated_report：AI 生成后的周报；
• model_name：使用的模型；
• created_at：创建时间。

1. app/db/database.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase
from app.core.config import settings


engine = create_engine(
    settings.DATABASE_URL,
    connect_args={"check_same_thread": False}
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine
)


class Base(DeclarativeBase):
    pass


def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

2. app/db/models.py

from datetime import datetime
from sqlalchemy import String, Text, DateTime
from sqlalchemy.orm import Mapped, mapped_column
from app.db.database import Base


class WeeklyReport(Base):
    __tablename__ = "weekly_reports"

    id: Mapped[int] = mapped_column(primary_key=True, index=True)
    user_name: Mapped[str] = mapped_column(String(100), index=True)
    raw_content: Mapped[str] = mapped_column(Text)
    generated_report: Mapped[str] = mapped_column(Text)
    model_name: Mapped[str] = mapped_column(String(100))
    created_at: Mapped[datetime] = mapped_column(
        DateTime,
        default=datetime.utcnow
    )

八、请求与响应模型

使用 Pydantic 定义接口输入输出，可以让代码更清晰，也便于生成接口文档。

app/schemas/report.py

from datetime import datetime
from pydantic import BaseModel, Field


class ReportCreateRequest(BaseModel):
    user_name: str = Field(..., min_length=1, max_length=100)
    raw_content: str = Field(..., min_length=5)


class ReportResponse(BaseModel):
    id: int
    user_name: str
    raw_content: str
    generated_report: str
    model_name: str
    created_at: datetime

    class Config:
        from_attributes = True

九、LLM 调用服务设计

AI 应用最核心的地方就是模型调用层。这里建议单独封装，不要在 API 层直接写 HTTP 请求。

app/services/llm_service.py

import httpx
from app.core.config import settings
from app.core.logger import app_logger


class LLMService:
    def __init__(self):
        self.api_key = settings.LLM_API_KEY
        self.base_url = settings.LLM_BASE_URL
        self.model = settings.LLM_MODEL
        self.timeout = settings.LLM_TIMEOUT

    async def generate_weekly_report(self, raw_content: str) -> str:
        prompt = self._build_prompt(raw_content)

        payload = {
            "model": self.model,
            "messages": [
                {
                    "role": "system",
                    "content": "你是一名专业的项目管理助理，擅长整理工作周报。"
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ],
            "temperature": 0.3
        }

        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        url = f"{self.base_url}/chat/completions"

        try:
            async with httpx.AsyncClient(timeout=self.timeout) as client:
                response = await client.post(url, json=payload, headers=headers)
                response.raise_for_status()
                data = response.json()
                return data["choices"][0]["message"]["content"]
        except Exception as e:
            app_logger.exception(f"LLM 调用失败: {e}")
            raise RuntimeError("AI 周报生成失败，请稍后重试")

    def _build_prompt(self, raw_content: str) -> str:
        return f"""
请根据以下工作内容生成一份结构化中文周报。

要求：
1. 语言专业、简洁；
2. 按以下结构输出：
   - 本周完成工作
   - 遇到的问题与风险
   - 下周工作计划
   - 需要协助的事项
3. 如果原始内容中没有明确提到某部分，请合理归纳，但不要编造具体事实；
4. 输出 Markdown 格式。

原始工作内容：
{raw_content}
"""

这里有几个关键点：

• 使用 system 消息定义模型角色；
• 使用明确的输出结构约束结果；
• temperature 设置为 0.3，减少随机性；
• 捕获异常并写入日志；
• 统一返回业务错误，避免把模型服务细节暴露给用户。

十、业务服务层

业务层负责协调 AI 服务和数据库操作。

app/services/report_service.py

from sqlalchemy.orm import Session
from app.core.config import settings
from app.db.models import WeeklyReport
from app.services.llm_service import LLMService


class ReportService:
    def __init__(self):
        self.llm_service = LLMService()

    async def create_report(
        self,
        db: Session,
        user_name: str,
        raw_content: str
    ) -> WeeklyReport:
        generated_report = await self.llm_service.generate_weekly_report(
            raw_content=raw_content
        )

        report = WeeklyReport(
            user_name=user_name,
            raw_content=raw_content,
            generated_report=generated_report,
            model_name=settings.LLM_MODEL
        )

        db.add(report)
        db.commit()
        db.refresh(report)

        return report

    def list_reports(self, db: Session, limit: int = 20):
        return (
            db.query(WeeklyReport)
            .order_by(WeeklyReport.created_at.desc())
            .limit(limit)
            .all()
        )

十一、API 接口实现

app/api/report.py

from typing import List
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session

from app.db.database import get_db
from app.schemas.report import ReportCreateRequest, ReportResponse
from app.services.report_service import ReportService


router = APIRouter(prefix="/reports", tags=["Reports"])
report_service = ReportService()


@router.post("", response_model=ReportResponse)
async def create_report(
    request: ReportCreateRequest,
    db: Session = Depends(get_db)
):
    try:
        return await report_service.create_report(
            db=db,
            user_name=request.user_name,
            raw_content=request.raw_content
        )
    except RuntimeError as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.get("", response_model=List[ReportResponse])
def list_reports(
    limit: int = 20,
    db: Session = Depends(get_db)
):
    return report_service.list_reports(db=db, limit=limit)

十二、应用入口文件

app/main.py

from fastapi import FastAPI
from app.api.report import router as report_router
from app.core.config import settings
from app.db.database import Base, engine
from app.db import models


Base.metadata.create_all(bind=engine)

app = FastAPI(
    title=settings.APP_NAME,
    description="AI 智能周报生成系统",
    version="1.0.0"
)

app.include_router(report_router)


@app.get("/health")
def health_check():
    return {
        "status": "ok",
        "app": settings.APP_NAME,
        "env": settings.APP_ENV
    }

启动服务：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

访问接口文档：

http://localhost:8000/docs

十三、Docker Compose 配置

如果你希望通过容器启动项目，可以添加如下配置。

docker-compose.yml

version: "3.9"

services:
  ai-weekly-report:
    image: python:3.11-slim
    container_name: ai-weekly-report
    working_dir: /app
    volumes:
      - ./:/app
    ports:
      - "8000:8000"
    env_file:
      - .env
    command: >
      sh -c "pip install -r requirements.txt
      && uvicorn app.main:app --host 0.0.0.0 --port 8000"

启动：

docker compose up -d

查看日志：

docker logs -f ai-weekly-report

十四、接口测试示例

使用 curl 创建周报：

curl -X POST "http://localhost:8000/reports" \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "张三",
    "raw_content": "本周完成了用户登录接口开发，修复了订单列表分页问题，参与了支付模块联调。遇到的问题是测试环境支付回调不稳定，下周计划完成订单导出功能和接口性能优化。"
  }'

可能返回：

{
  "id": 1,
  "user_name": "张三",
  "raw_content": "本周完成了用户登录接口开发，修复了订单列表分页问题，参与了支付模块联调。遇到的问题是测试环境支付回调不稳定，下周计划完成订单导出功能和接口性能优化。",
  "generated_report": "## 本周完成工作\n- 完成用户登录接口开发...\n",
  "model_name": "deepseek-chat",
  "created_at": "2025-01-01T10:00:00"
}

查询历史周报：

curl "http://localhost:8000/reports?limit=10"

十五、AI 编程过程中的常见问题

1. AI 生成的代码能不能直接用？

不建议完全照搬。AI 生成代码可以作为初稿，但仍然需要开发者检查：

• 是否符合业务需求；
• 是否存在安全风险；
• 是否有异常处理；
• 是否符合项目规范；
• 是否容易维护；
• 是否有性能问题。

AI 很适合提升效率，但不能替代工程判断。

2. Prompt 应该怎么写？

好的 Prompt 应该包含：

• 技术栈；
• 目标功能；
• 输入输出；
• 约束条件；
• 代码风格；
• 异常处理要求；
• 是否需要注释；
• 是否需要测试用例。

例如：

请使用 FastAPI 编写一个创建周报的接口。
要求：
1. 使用 Pydantic 校验请求参数；
2. 使用 SQLAlchemy 保存数据；
3. 调用 LLMService 生成周报；
4. 捕获模型调用异常并返回 HTTP 500；
5. 代码风格简洁，适合生产项目。

3. 如何避免 AI 乱编接口？

在使用第三方 SDK 或框架时，可以给 AI 提供真实文档片段，或者要求它只使用你指定的接口。

例如：

请只使用 httpx.AsyncClient.post 方法调用接口，不要引入不存在的 SDK。

4. 如何让 AI 生成更稳定的结果？

对于 AI 应用本身，可以从两方面控制。

第一是模型参数：

{
  "temperature": 0.3,
  "top_p": 0.8
}

第二是 Prompt 约束：

请严格按照以下 Markdown 模板输出，不要增加额外说明。

十六、可扩展方向

这个智能周报系统只是一个基础版本，后续可以继续扩展：

1. 用户体系

增加用户注册、登录、权限控制，让每个人只能查看自己的周报。

2. 模板管理

支持不同团队配置不同周报模板，例如研发周报、运营周报、销售周报。

3. 多模型切换

支持在配置中切换模型，或者在请求参数中指定模型。

4. 接入项目管理平台

可以从 Jira、禅道、Tapd、飞书任务、GitLab Issue 等系统自动拉取任务数据。

5. 自动总结团队周报

管理者可以一键汇总团队成员周报，自动生成项目进度摘要、风险列表和下周重点。

6. 定时任务

每周五自动提醒填写周报，每周一自动发送汇总报告。

7. RAG 增强

接入知识库，让 AI 了解项目背景、模块说明、人员分工，从而生成更准确的周报内容。

十七、本案例的核心收获

通过这个案例，我们可以看到 AI 编程并不是简单地“让 AI 帮我写代码”，而是一种新的协作开发方式。

开发者仍然需要负责：

• 判断需求是否合理；
• 设计项目架构；
• 控制代码边界；
• 审查 AI 生成内容；
• 做异常处理；
• 管理配置和部署；
• 保障数据安全。

AI 更像是一个高效的工程助手，可以帮助我们：

• 快速生成项目骨架；
• 补齐样板代码；
• 编写配置文件；
• 生成接口示例；
• 优化 Prompt；
• 排查错误；
• 编写文档。

真正高质量的 AI 编程实践，关键不在于让 AI 一次性完成所有事情，而在于把任务拆得足够清楚，让 AI 在明确边界内完成具体工作。

十八、总结

本文围绕“AI 编程实战案例”完整分享了一个智能周报生成系统的开发过程，包括需求背景、技术选型、项目结构、配置文件、数据库模型、LLM 服务封装、业务逻辑、API 接口、Docker Compose 部署以及后续扩展方向。

如果你正在学习 AI 编程，建议不要只停留在简单代码片段生成，而是尝试用 AI 完成一个完整项目。哪怕项目很小，也要包含配置管理、日志、数据库、接口、异常处理和部署方式。这样才能真正理解 AI 编程在工程实践中的价值。

AI 不会自动让项目变得优秀，但会显著放大开发者的效率。你的架构能力、工程经验和问题拆解能力越强，AI 能发挥的价值就越大。