三步跟练

这一页就能跟完三步

从空项目做出工作日 API、普通聊天网页，再让模型调用 API。制作指令发给 Qoder；测试问题发到自己搭建的网页。每一步检查通过再继续。深入阅读用于了解原理，可在完成后再看。

开始前：用 Qoder 打开一个空文件夹

1. 在电脑中新建 workday-agent 文件夹，用 Qoder 打开，在编程任务中开始。下面三条提示词在同一任务中依次发送。
2. 环境检查、Python 和依赖安装、启动服务都交给 Qoder。遇到系统授权或账号登录，按提示自己确认；无需先手动准备 Python 环境。
3. 第二步才需要模型服务的 API Key、Base URL 和 Model。先查该服务是否兼容 OpenAI Chat Completions、所选模型是否支持 Tool / Function Calling。Qoder 订阅和应用调用模型的费用通常分别计算。

本课在自己的电脑运行，127.0.0.1 指本机。以下示例端口为 8000；以 Qoder 给出的实际地址为准。端口占用让 Qoder 换端口并同步工具地址；服务关闭后让它重新启动。安装或网络失败，把错误交给 Qoder 处理，不必先学会终端命令。

第一步：工作日查询 API

做什么

用 Qoder 打开新建的空文件夹 workday-agent，在编程任务中发送下面提示词。环境检查、安装依赖、启动和修复由 Qoder 完成；按需确认系统安装操作。

发给 Qoder

用 FastAPI 做工作日查询 API：输入年份、月份，返回工作日数量、日期清单和调休补班日期。日历用 https://unpkg.com/holiday-calendar@1.3.3/data/CN/{year}.json，按中国大陆普通双休计算，未知年份和无效月份报错。请检查并配置所需环境，安装依赖，只在本机启动，告诉我 /docs 地址和如何试查 2026 年 10 月。先不做聊天。

应该看到什么

打开 Qoder 给出的 /docs 地址，用 Swagger 发出请求。2026 年 10 月应有 18 个工作日，补班日期含 2026-10-10。

怎么检查

再查询 2026 年 2 月，应为 16 天。月份 13 和没有数据的年份应报错。

亲手用 Swagger 查一次

1. 打开 Qoder 给出的 http://127.0.0.1:8000/docs。这是接口的交互文档。
2. 找到并展开 GET /workdays，点击 Try it out。
3. 在 year 填 2026，month 填 10，点击 Execute。
4. 往下看 Server response → Response body 的真实返回。不要把 Example Value 示例当成运行结果。

再查 2026 年 2 月，应为 16 天，补班日含 2 月 14 日、28 日。月份改 13 应报错，2030 年应说明没有数据。若生成的接口名不同，让 Qoder 指出对应项或改为 /workdays。

刚才的查询与预期不一致。请检查真实返回的数据结构和工作日规则，修好后重跑这几个查询。

这里使用开源日历整理数据，由 UNPKG 分发，不是政府官方 API。按普通双休计算，固定版本覆盖至 2026 年；企业排班不适用。本课样例对照国务院 2026 年放假安排核对。

第二步：普通聊天 AI

做什么

继续在同一个 Qoder 任务中发送提示词。等它生成配置样例，再按下方说明填入自己选择的服务商信息。

发给 Qoder

在现有项目上做一个类似 ChatGPT 的聊天网页，支持连续对话和新建对话。后端用 OpenAI Chat Completions 兼容接口，从 .env 读取 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL，生成 .env.example 让我填写，密钥不进前端、日志或 Git。先不接工作日工具，配置后在本机启动并验证聊天，告诉我打开哪个地址。

应该看到什么

打开聊天网页，发“我叫小林”，再问“我叫什么”，应接着对话回答小林；新建对话再问，应不再记得。

怎么检查

这一步只验证模型连接和聊天。即使它答对工作日，也没有证明它读取了第一步 API。

填写模型配置，启动网页

LLM API 就是让程序向模型发送消息、接收回答的接口。网页把你的消息交给本机后端，后端再请求模型服务。你使用哪家服务，就从哪家取得以下配套信息：

协议约定请求和回答怎么组织。本课使用 OpenAI Chat Completions 兼容格式：用 messages 传对话，model 指定模型，第三步再加 tools 并回传工具结果。兼容这种格式的其他服务也可配置；仍要确认具体模型支持工具调用。只有不同原生协议的接口，需要 Qoder 另外适配，不能只换网址。

LLM_BASE_URL=服务商提供的接口基础地址
LLM_API_KEY=在本机填入自己的密钥
LLM_MODEL=服务商的准确模型编号

DeepSeek 只是本课已实测的示例：Base URL 为 https://api.deepseek.com/v1，Model 可填 deepseek-flash；自己的 Key 从其开放平台取得。其他服务照自己的官方文档填写。参考项目通过 LLM_EXTRA_BODY 接收必要的服务商专属参数，默认 {}；DeepSeek 示例使用 {"thinking":{"type":"disabled"}} 关闭思考以减少课堂等待。不要给其他服务照抄专属参数。

API Key 只在本机后端保存，不进入前端、提示词、截图和仓库。Qoder 或 ChatGPT 的订阅通常不等于模型 API 额度。调用、连续对话和每一轮工具结果回传都可能消耗额度；具体费用由你选择的服务和模型决定。

1. 等待 Qoder 生成 .env.example；在 Qoder 的文件列表中复制为同一目录的 .env。找不到文件操作时让 Qoder 创建空配置并打开文件。
2. 在文件编辑器中填入对应服务商的 Base URL、API Key、模型编号并保存。不要把密钥贴进 Qoder 对话。文件名避免变成 .env.txt。
3. 回到 Qoder 说：“配置已填好，请启动服务并给我聊天地址，不要输出密钥。”
4. 打开地址，在新网页发送“我叫小林”，再问“我叫什么”。点新建对话，再问相同问题。

按 .env 的 LLM_MODELS（逗号分隔）增加模型选择，默认 LLM_MODEL。后端只接受配置中的模型，切换时新建对话，页面显示当前模型。先验证普通聊天，不接工作日工具。

聊天没有正常返回。请在不输出密钥的前提下检查配置、模型名称和服务响应，并告诉我最小修复方式。

第三步：接上工具与循环

做什么

在同一个 Qoder 任务中继续发送提示词。打开更新后的聊天页面，选择工具模式，新建对话后提问。

发给 Qoder

把第一步工作日 API 注册成聊天 AI 的 function tool，由模型决定调用，不用关键词分支。收到 tool call 后实际 HTTP 请求该 API，再把结果作为 tool 消息交回模型，最多 3 轮工具调用。页面显示工具名、参数、HTTP 请求、工具结果和最终回答，保留普通聊天模式作对照。缺年份先追问，API 失败说明原因，不猜数据。启动并用 2026 年 10 月验证。

应该看到什么

问“2026 年 10 月有几个工作日，哪天补班？”应得到 18 天、10 月 10 日，并看到真实调用记录。

怎么检查

再问“比较 2026 年 2 月和 10 月的工作日”，应查询两个月，得到 16 天与 18 天；问“10 月有几个工作日”应先问年份；一般闲聊不必调用。

在你搭建的网页里提问

1. 让 Qoder 重启，刷新聊天网页，选择工具模式并新建对话。
2. 问：“2026 年 10 月有几个工作日，哪天补班？”
3. 展开执行记录，核对 get_workdays 的 year=2026、month=10，真实 HTTP 请求成功，结果是 18 天、10 月 10 日补班。
4. 核对模型在接到结果后给出最终回答。不能只有一句“已调用工具”。

请核对这次真实工具调用和 HTTP 记录：是否调用了第一步 API、把结果交回模型。修复缺失环节并重跑，不能用写死答案代替。

完成检查：每题新建对话再试

若增加多个模型，每个模型分别新建对话核对。程序算对不代表所有问法都理解正确，修改后要重测代表问题。

卡住时可以下载完整参考项目，用 Qoder 打开解压目录，说：“按 README 配置并启动，密钥由我在 .env 填写，不要输出密钥。”这是已完成三步的版本。理解 FastAPI 的选择理由 · 深入理解 Agentic 循环 · 实跑范围与限制