日志、成本与 README 完善

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

学习目标

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

• 为综合项目补齐最小日志。
• 记录模型调用的基本成本信息。
• 写出可供他人快速上手的 README。

前置知识

• 已完成项目主功能

1. 日志最少记录什么

至少记录以下事件：

• 服务启动
• 模型调用开始
• 模型调用结束
• 工具执行开始
• 工具执行结束
• 错误发生

建议每条日志至少携带：

• 模块名
• 模型名
• 工具名
• 成功/失败

2. 成本统计最低要求

月份 1 不要求你做专业计费系统，但至少要能回答：

• 调用了哪个模型
• 调用了多少次
• 某次调用是否成功
• 输出大概有多长

如果接口返回 usage，再记录输入输出 token。

3. README 必须包含什么

项目简介

一句话说清楚项目是干什么的。

功能范围

明确列出做了什么、没做什么。

环境准备

• Python 版本
• uv 安装
• DeepSeek API Key

启动步骤

• 安装依赖
• 配置 .env
• 启动 CLI
• 启动 FastAPI

使用示例

• 一个 CLI 示例
• 一个 API 示例

项目结构

简单说明目录职责。

已知限制

例如：

• 仅支持单轮或短多轮
• 工具集合很小
• 暂不支持知识库

4. 为什么 README 是验收的一部分

因为一个别人 10 分钟内跑不起来的项目，在作品集里价值会大打折扣。

5. 实操任务

1. 给项目加日志
2. 记录至少一次模型调用信息
3. 补完整 README

6. 自测题

1. 为什么日志和成本统计不是“以后再说”的事情？
2. README 最常见的失败点是什么？
3. 为什么已知限制要写出来？

7. 验收标准

• 至少能看到关键日志
• 至少有基础调用记录
• README 可以指导别人启动项目

8. 本章与前文关系

上一章已经让综合项目具备了：

• CLI 入口
• FastAPI 入口
• 核心业务层

现在项目进入最后一个非常关键的阶段：把“能跑的半成品”整理成“能解释、能展示、能复现的作品”。

9. 本章在研发助手项目中的位置

如果没有日志、调用记录和 README，项目会出现三个问题：

• 你自己以后很难排查
• 别人很难复现
• 面试或演示时很难讲清楚

所以这一章并不是在补“文档工作”，而是在补作品集质量。

10. 一个最小日志接入示例

from app.logger import get_logger


logger = get_logger(__name__)


def record_tool_execution(tool_name: str, success: bool, detail: str) -> None:
    logger.info(
        "tool_execution | tool_name=%s | success=%s | detail=%s",
        tool_name,
        success,
        detail,
    )

这类最小日志已经足以帮助你在录屏或复盘时说明：

• 这个阶段发生了什么
• 成功还是失败
• 当前操作对应哪个模块

11. 一个更完整的 README 思路

你不只是要“写 README”，而是要让 README 成为：

• 启动指南
• 结构说明
• 展示说明

一个最小可用的 README 提纲应包含：

1. 项目简介
2. 功能范围
3. 环境准备
4. CLI 用法
5. API 用法
6. 目录结构
7. 已知限制

12. 为什么“已知限制”必须写出来

因为它能帮助你建立成熟的工程表达习惯。

月份 1 项目并不追求“什么都支持”，相反，你应主动说明：

• 目前只支持哪些功能
• 暂不支持什么
• 为什么还没有做某些功能

这会让你的项目更可信，而不是更弱。

13. 调试与排错：本章最常见问题

问题一：日志只有“开始”和“结束”，没有上下文

这类日志对排查价值很低。

问题二：README 写得像功能清单，没有操作步骤

别人依然很难跑起来。

问题三：调用记录没有最小统计信息

这样你无法解释项目在真实使用中的成本意识。

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

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

1. 能为项目补最小可观察性。
2. 能写出真正可执行的 README。
3. 能把项目从“练习代码”整理成“作品级输出”。

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

接下来进入 05-项目验收与录屏脚本.md。

因为到这里，项目代码和文档都已经基本齐了。最后一步就是做验收和展示设计，让这个项目真正成为月份 1 的闭环成果，而不是留在本地目录里的一个半成品。

16. 为什么 README 不是“最后随便补一补”

一个成熟的 README 至少承担 3 个角色：

• 给未来的你看
• 给协作者看
• 给面试官或评审看

所以月份 1 不希望你把 README 写成一份仅自己看得懂的备忘录。它应该做到：

• 10 分钟内让别人跑起来
• 3 分钟内让别人理解项目定位
• 1 分钟内让别人知道当前边界和限制

17. 调用记录应该如何与 README 配合

你不一定需要在 README 里贴出复杂的监控图表，但至少应该说明：

• 项目已经记录哪些日志
• 记录了哪些调用信息
• 遇到失败时如何查看排查线索

这样做的价值在于：别人会知道这不是“只有 happy path 的 demo”，而是考虑过真实调试过程的项目。

18. 一个更成熟的作品集表达方式

如果你想把项目做得更像“课程博客 + 作品集”，可以在 README 末尾增加一个小节：

本项目体现的月份 1 能力

• Python 工程化
• LLM API 接入
• Tool Calling 闭环
• FastAPI 服务化
• 最小测试与可观测性

这会让项目和课程主线之间的关系更显性。

16. 为什么 README 不是“最后随便补一补”

一个成熟的 README 至少承担 3 个角色：

• 给未来的你看
• 给协作者看
• 给面试官或评审看

所以月份 1 不希望你把 README 写成一份仅自己看得懂的备忘录。它应该做到：

• 10 分钟内让别人跑起来
• 3 分钟内让别人理解项目定位
• 1 分钟内让别人知道当前边界和限制

17. 调用记录应该如何与 README 配合

你不一定需要在 README 里贴出复杂的监控图表，但至少应该说明：

• 项目已经记录哪些日志
• 记录了哪些调用信息
• 遇到失败时如何查看排查线索

这样做的价值在于：别人会知道这不是“只有 happy path 的 demo”，而是考虑过真实调试过程的项目。

18. 一个更成熟的作品集表达方式

如果你想把项目做得更像“课程博客 + 作品集”，可以在 README 末尾增加一个小节：

本项目体现的月份 1 能力

• Python 工程化
• LLM API 接入
• Tool Calling 闭环
• FastAPI 服务化
• 最小测试与可观测性

这会让项目和课程主线之间的关系更显性。