10 实践课-分拣场景全流程开发实战

分拣场景全流程开发实战

关联：索引

  1. 场景提问：同一个“今天 LINE-01 分拣了多少？合格率是多少？”的需求，为什么有人卡在 Key，有人卡在 API 401，有人卡在输出字段不稳定？如何用证据快速判断卡在哪一环？

目标：让项目“先能跑”，并把常见环境问题变成可定位的报错。

推荐口径（够用即可）：

环境校验最低要求：

对照 greensort_teaching_demo 的实操步骤（学生照做版）：

  1. 进入项目目录并确认解释器是 3.10：
cd ".\greensort_teaching_demo"
python --version
python -m pip --version
  1. 安装依赖并做“能 import”校验：
python -m pip install -r .\requirements.txt
python -c "import httpx; import dotenv; print('deps ok')"
  1. 配置 .env 并做“配置校验”：
notepad .\.env
python -c "from student_agent.config import load_settings, validate_settings; validate_settings(load_settings()); print('settings ok')"

目标：不依赖智能体，先把 API 当成“普通服务”跑通。

最小 API 调用清单（至少跑通 2 个，建议 4 个全跑）：

对齐项目接口文档的最小请求样例（可复制改参数）：

POST /api/v1/auth/login
Content-Type: application/json

{"username":"admin","password":"admin123"}

GET /api/v1/sorting/realtime-stats?line_id=LINE-01
Authorization: Bearer {access_token}

对照 greensort_teaching_demo 的实操方法（先用 Swagger UI 验证，再看代码）：

  1. 启动 mock API（终端 1）：
cd ".\greensort_teaching_demo"
python -m uvicorn mock_server.app:app --host 127.0.0.1 --port 8000
  1. 打开浏览器进入 Swagger UI（FastAPI 自带）：
  1. 在 Swagger UI 中按顺序验证（无需写代码）：
  1. 再对照代码把“Swagger 上点过的请求”写成可复用函数：

目标：把“最终输出格式”固定下来，让后续工具与智能体都能对齐。

对照 greensort_teaching_demo 的实操方法（从模板→到端到端输出）：

  1. 打开模板文件，找到 5 类输出前缀与字段拼接：
  1. 跑一次端到端，观察输出是否满足契约（终端 2）：
cd ".\greensort_teaching_demo"
python -m student_agent.app
  1. 修改模板后必须回归：
python -m student_agent.tests_smoke

目标：把“意图识别→路由→工具→输出模板”串起来，并确保每条路径都有证据字段。

建议路由口径（够用即可）：

对照 greensort_teaching_demo 的组装步骤（从“能跑”到“可回归”）：

  1. 意图识别与槽位抽取：看 student_agent/intent.py
  2. 工具封装：看 student_agent/tools_sorting.py
  3. 端到端入口：看 student_agent/app.py 的 handle_one_turn
  4. 回归测试：看 student_agent/tests_smoke.py
cd ".\greensort_teaching_demo"
python -m student_agent.tests_smoke

目标：把“看起来坏了”拆成“哪一环节坏了”，并用证据快速收敛。

  1. 环境是否可信：Key/URL/依赖是否 OK（配置校验证据）
  2. API 是否可信：同样入参，独立 API 调用是否成功（http_status/trace_id）
  3. Prompt 是否可信：输出字段是否齐全且稳定（模板字段检查）
  4. 智能体是否可信：路由是否正确、工具是否被触发、结果是否回填（消息链与最终输出证据）

对照 greensort_teaching_demo 的故障注入实操（复现→定位→修复→回归，推荐 Swagger UI）：

前置：打开 http://127.0.0.1:8000/docs，先用 POST /api/v1/auth/login 登录拿到 access_token；后续所有需要登录的接口，都在 authorization header 参数里填写：Bearer <token>。

  1. 权限 403（AUTH_004）：不带 X-Role: admin 触发急停
{"target":"system","action":"emergency_stop","params":{}}

定位方法：记录 http_status=403 + 错误体里的 error_code/path/trace_id，再对照 mock_server/app.py 的权限判定逻辑解释“为什么是权限环节”。

  1. 超时 504（ROS_002）：模拟 ROS 超时
{"target":"arm","action":"simulate_timeout","params":{}}

定位方法：用 trace_id 把一次请求与一次故障对上；解释“API 可达但设备控制超时”属于执行环节。

  1. 限流 429（SYS_003）：短时间内重复请求触发全局限流

定位方法：用错误体的 error_code=SYS_003 解释“不是参数问题/不是 token 问题，而是请求频率问题”，给出“降低频率/退避重试/缓存结果”的修复策略。

  1. 修复后必须回归（终端 2）：
cd ".\greensort_teaching_demo"
python -m student_agent.tests_smoke

跨环节定位结论要落到“可执行动作”：

目标：至少 2 个环节用 AI 提速，但必须“给证据、要结构化输出、做复验”。

环节 1（推荐）：Prompt 模板优化
输入给 AI：

要求 AI 输出（结构化）：

人工审计点：

环节 2（推荐）：跨环节故障定位与修复建议
把“证据三件套”喂给 AI（必须给全）：

要求 AI 输出：

1）判断故障属于哪个环节（环境/API/Prompt/工具/路由/回填）
2）根因排序（Top 3）
3）最小改动方案（只改 1 个点）
4）复验步骤（至少 3 条）与预期证据字段

建议把 AI 的输出绑定到项目文档（避免胡编）：

目标：用最小测试脚本固化“能跑通”的标准，修复后必须回归。

业务场景可替换模板（让学生学完能迁移到自己的业务）

把你自己的项目文档放在桌面，按下面 6 个“可替换槽位”替换本里的示例即可迁移：

  1. 业务对象：水果/零件/工单/客服/巡检……（一句话说清“系统为谁服务”）
  2. 核心流程：输入→处理→输出（画 5 个以内节点，标出数据落库点）
  3. 关键实体字段：至少 5 个（例如本项目：line_id/batch_id/fruit_id/grade/trace_id）
  4. 核心接口清单：至少 4 个（认证 + 2 个业务查询/写入 + 1 个控制/动作）
  5. 错误码与降级策略：至少 3 个（超时/鉴权/外部依赖不可用）
  1. 全流程跑通：至少 4 条端到端用例覆盖 4 类输出。
  2. 至少 1 个跨环节问题完成闭环：复现→定位→修复→回归（证据链完整，含 trace_id/parse_trace_id）。
  3. AI 辅助 ≥ 2 个环节，并能说明：AI 给了什么建议、你审计了什么、最终改了哪一处。
  4. Smoke Test 结果可出示（通过或失败列表 + 定位结论）。

现场出示的证据清单（建议统一口径）：

作业（布置）

  1. 环境与运行证据：
  1. API 证据：
  1. 端到端证据：
  1. 回归证据：
  1. 协作与审计证据：

最终作业的要求与提交形式以第 11 讲的“作业（布置）”为准。