高级全栈与 FDE 工程学习手册四周 · 88 小时

第 3 周|让助手使用工具,把系统部署起来

22 小时,D15–D21。 你已经有生成任务和带出处的检索接口。现在给教案工作台加一位任务助手。用户可以问“那次生成卡在哪”“这个要求依据哪条规范”,或在看完失败原因后决定重试。第三周末,你要能在新环境从登录演示到确认重试,随后拿着任务编号查出实际发生了什么。

开工条件。 准备两个账号 A、B,分别有自己的教案或私有资料。给 A 留一个失败任务、一个正在运行的任务。第 2 周的向量检索若仍在调优,这周先用能按权限返回引用的关键词检索。接模型前先用可编程的假模型,让它按你指定的顺序返回工具请求,等控制逻辑通过再换真实模型。

本篇目录

D15 · 先写一条固定工作流|2 小时

原理。 工作流由代码决定下一个步骤。Agent 则允许模型根据当前结果决定下一次调用哪个工具。查询任务状态的步骤很稳定,用工作流就能完成。用户把“任务为什么失败”和“教案时长怎么填”放进同一个问题时,动态选择工具才有价值。Anthropic 工作流与 Agent 设计

  1. 20 分钟画图。 在纸上画出“收到任务 ID → 按登录用户查任务 → 按状态返回解释”。如果没给任务 ID,就提示用户选择一个任务;失败则显示可公开的错误摘要。
  2. 55 分钟实现。 给任务详情页加“解释状态”。通过服务端复用原有任务查询函数,函数入参包含登录主体和任务 ID。把四种状态映射成一两句有用的中文。
  3. 30 分钟验证。 对成功、运行中、失败、其他人任务各跑一次。失败案例可用自造的上游超时。核对交给用户的是可展示的摘要。
  4. 15 分钟留证。 留下一张流程图和一条脱敏样例。用两句话回答“为什么这一步能确定性执行”“什么问题会需要检索工具”。

卡住时。 如果任务接口只有一段异常堆栈,先整理成短字段 error_code 和面向用户的 message。技术细节可以通过关联 ID 在服务端追查。

D16 · 写出模型能够正确调用的两个工具|2 小时

原理。 工具描述告诉模型何时选择这个能力。参数 Schema 定义输入格式。执行权留给应用,应用从会话取身份、校验资源并执行业务函数。工具结果要带回原始调用标识,让下一轮模型能将观察结果与请求对上。客户端工具调用 · JSON Schema 对象约束

验收。 用户 A 查询自己的任务能看见真实状态。查询 B 的私有任务只得到通用的资源不可用反馈。工具定义和返回内容中都能看出它的业务边界。

D17 · 写一个会停下来的工具调用循环|2 小时

原理。 把一轮交互看作“提出动作 → 应用校验并执行 → 返回观察值”。对话历史帮助模型理解问题,任务状态由数据库提供。工具调用次数、端到端时限、单次调用超时和输出长度分别限制不同的资源。

卡住时。 日志若反复出现同一条查询,检查历史是否同时写入原始工具请求及对应的工具结果,确认 SDK 要求的调用 ID 是否传回。先用假模型锁定协议问题,再改提示词。

D18 · 把重试做成可确认、可重放的写操作|2 小时

场景。 用户说“如果是超时就帮我重试”,助手先读到失败状态,提出具体重试动作。前端显示任务编号、当前尝试次数、将执行的动作和有效期。用户点按钮后,后端再次检查身份、归属和任务状态。

验收。 有提议但用户取消时,数据保持原状。确认响应丢失后重放请求时可以取回原回执。并发测试留到 D20 扩展。

D19 · 让助手的行为能够评分|2 小时

原理。 同一句“已经处理”可能对应正确重试,也可能根本没有入库。测试要同时看工具轨迹、最终文字及数据库前后差异。

  1. 20 分钟选实验手册前五个场景,先写预期的工具集合、允许的结果和禁止出现的副作用。
  2. 50 分钟建立测试入口。每个场景有独立的数据准备、假模型脚本、输入、预期状态和清理方式。记录 run_id,通过它关联请求、任务及工具事件。
  3. 30 分钟跑一次确定性测试;选“单查状态”和“查状态并找规范”各跑一次真实模型,记下偏差、耗时和用量。
  4. 20 分钟挑一个失败用例,只调整一个因素,例如工具描述对“查询”和“重试”的区分,再次运行。

面试追问。 工具选对了、参数正确,用户仍然没完成任务,可能是哪一层出了问题?从状态已改变、确认过期、证据过时、最终回复错误各举一例。

D20 · 长练习:从失败诊断到人工确认|6 小时

时间 动手任务 留下的证据
45 分钟 在任务详情页增加对话入口和工具摘要,准备 A、B 两组数据 一页测试数据说明
85 分钟 串起只读查询、资料引用、生成提议和确认按钮 一个失败任务的完整交互记录
70 分钟 补实验手册剩余场景,重点验证取消、重复确认、状态改变和其他用户资源 十个场景的预期与实际结果
60 分钟 模拟并发确认、工具超时和无穷重复请求。用上限和超时记录证明退出路径有效 一条并发轨迹和一条预算耗尽轨迹
55 分钟 在同样的输入上比较固定工作流与 Agent,记录解决情况、模型调用数、耗时。对路线不支持的请求标注“转人工/要求澄清” 一张小样本对照表
45 分钟 修复最影响验收的一项问题并复测。用自己的话解释一次工具执行和一次写入授权 修复前后两条证据

进度落后时。 保留任务状态、资料检索和重试确认三个能力;界面可以只用任务详情、一张确认卡和一列事件历史。演示时,用真实的查询结果回答“这个回答依据什么”。

D21 · 长练习:首次可复现部署|6 小时

时间 动手任务 验收点
45 分钟 列运行依赖、构建入口、数据库扩展、持久化目录、模型配置。选择练习用端口 一个配置样例,只包含示范值
80 分钟 配好 app、worker、db 服务。app 可同时提供前端构建产物;worker 使用同版业务代码。为数据库、资料存储配置持久卷 服务通过健康检查,重启后资料可用
65 分钟 为迁移设置单一入口,为数据库设置就绪条件。再导入两组可复现的实验数据 新环境启动后能登录并查到种子教案
65 分钟 用新项目名和独立卷运行 Compose,逐项验收上传、查询、提议和确认 一次冷启动记录、一个可追踪的任务编号
60 分钟 重启一次 worker 与应用,复测资料、任务和重复确认回执 两个真实检查结果及修复记录
45 分钟 整理 README,写清构建、迁移、启动、健康检查、演示、观察日志和普通停机步骤 另一位工程师能按文档完成演示

可采用的首次部署顺序。 在 Compose 中定义 db、migrate、app、worker 四个服务。migrate 运行你所选框架的数据库迁移命令。db 定义健康检查;migrate 等待 db 健康;app 和 worker 等待 migrate 成功结束。下面命令假设已准备镜像构建文件、Compose 配置和示例环境变量,项目名使用你本次验收的唯一名字,服务名按上文设置。将需要验收的应用端口配置成可调,避免与开发实例冲突。先确认数据库和文件均使用按项目隔离的卷。Docker Compose 服务依赖和健康检查

docker compose -p lesson-study-check config --quiet
docker compose -p lesson-study-check up -d --build
docker compose -p lesson-study-check ps -a
docker compose -p lesson-study-check logs --tail=80 migrate app worker

migrate 正常结束的退出码应为 0。遇到“数据库连不上”,先核对容器内数据库主机名是 Compose 的服务名 db,再查凭据、健康状态及迁移日志。普通停机使用同项目名的 docker compose ... down,保留卷供回归。模型额度或网络暂不可用时,可先用模拟模型做部署验收,另列真实 API 调用的验证状态。

本周面试演示,限时三分钟。 先现场查一个任务状态,再问一个需要找出处的问题,最后演示一次确认重试。在日志中找到对应调用,然后展示 worker 再次领取后原任务的 attempt 增加一次。讲清一个由模型做的决定、一个由程序固定的约束,以及一项你能提供实测证据的改进。