11 实践课-开发成果验收与优化

关联：索引

  1. 场景提问：同样是“能跑的智能体”，为什么交付时有人被打回？常见原因是代码不可读、错误处理不全、证据字段缺失、用例无法复现。

目标：用统一口径审代码，避免“凭感觉改”。

  1. 规范性（风格与契约）
  1. 可读性（结构与复杂度）
  1. 功能性（需求覆盖）
  1. 鲁棒性（异常与降级）

对照 greensort_teaching_demo 的“逐文件审计法”（照着走一遍，就能写出第 7 节审计报告）：

审计目标不是“挑语法毛病”，而是把“交付风险”找出来：别人能不能复现、失败能不能定位、修复能不能回归。

1）先用 Smoke Test 把“可复现入口”固定住（后续所有修复都以它为回归证明）：

cd ".\greensort_teaching_demo"
python -m student_agent.tests_smoke

2）按模块职责逐个过（建议每组分工：每人负责 2 个文件，最后合并问题清单）：

最小审计清单模板（可直接复制到小组记录）：

本节产出写法（用于作业模板第 7 节）：

编号 分类 风险等级 现象/证据（含 trace_id/http_status/error_code） 根因判断 建议修改 是否已修复
Q-01 规范性 中 ... ... ... 否
  1. 功能完整性：需求覆盖，关键路径可跑通
  2. 准确率：关键字段与计算结果符合预期（至少能解释口径并可复验）
  3. 稳定性：重复运行结果一致，异常分支能给出明确可执行提示

1）API 成功用例（至少 2 次独立调用）：

$base="http://127.0.0.1:8000"
$loginBody='{"username":"admin","password":"admin123"}'
$token=(Invoke-RestMethod -Method Post -Uri "$base/api/v1/auth/login" -ContentType "application/json" -Body $loginBody).access_token
$auth="Bearer $token"

Invoke-RestMethod -Method Get -Uri "$base/api/v1/sorting/realtime-stats?line_id=LINE-01" -Headers @{authorization=$auth}
Invoke-RestMethod -Method Get -Uri "$base/api/v1/sorting/records?line_id=LINE-01&grade=A&limit=20" -Headers @{authorization=$auth}

2）异常覆盖用例（至少 2 类，推荐直接用“故障注入点”保证可复现）：

3）端到端输出（4 类输出各 1 条，推荐从 python -m student_agent.app 取证）：

4）回归证明（Smoke Test）：

本节补齐并归档到作业 PDF（对应模板第 3–6 节）：

目标：把审计发现落到“最小修改 + 回归证据”。

  1. 再补错误分支：把 401/403/429/504 等常见错误区分开（输出 error_code + trace_id）
  2. 再控输出稳定：统一输出格式，避免字段名漂移
  3. 最后做回归：每修一处立刻跑 Smoke Test

回归口径（复用上一讲）：

修复闭环写法（用于作业模板第 8 节，至少 2 个）：

  1. 复现：写清复现命令/输入与“修复前输出证据”（必须含证据字段）
  2. 定位依据：说明为什么判断是这个环节（配置/API/工具/路由/Prompt/测试）
  3. 修改点描述：只描述改动点与影响范围（避免贴大段代码）
  4. 修复后对比：同一用例再次执行的关键输出片段（含证据字段）
  5. 回归证明：Smoke Test 输出（通过或失败列表；失败要能定位环节）

把“修复闭环”写成可抽测复现的格式（建议直接复制下面小模板）：

闭环 #（引用问题编号：Q-xx）：

开发文档推荐结构（可直接照搬）：

最终以“作业（布置）”给出的模板为准。本节课只做两件事：

  1. 把模板第 3–6 节写到可抽测复现：命令可执行、参数明确、证据字段可对照
  2. 把模板第 9 节补齐：文档结构调整前/后对比 + 缺口补齐清单（命令/截图/字段/复验步骤）

截图与记录清单（建议对照补齐）：

把证据“按模板填进去”的最快做法（对应作业模板第 3–6 节，建议按顺序完成）：

你们最终只交 1 个 PDF，所以要把证据直接写进 Markdown 正文中。建议每节都按“命令/操作 → 输出/截图 → 关键字段标注”的三行结构来写。

1）第 3 节 环境与运行（必须可复现）：

cd ".\greensort_teaching_demo"
python --version
python -m pip install -r .\requirements.txt

2）第 4 节 API 验证证据（至少 2 成功 + 至少 2 异常）：

3）第 5 节 Prompt 与输出契约（4 类输出样例）：

python -m student_agent.app

python -m student_agent.tests_smoke

导出前检查：截图可读、命令可复制、不要出现真实密钥/Token 全量字符串。

目标：用 AI 加速，但不把质量责任外包给 AI。

环节 1（推荐）：AI 辅助代码审计
输入给 AI（必须提供证据）：

要求 AI 输出（结构化）：

1）问题清单（按规范/可读/功能/鲁棒分类）

2）风险等级（高/中/低）与原因

3）最小修改建议（尽量只改 1 个点）

4）复验步骤（至少 3 条）与预期证据字段

人工审计点：

本节产出落地（用于作业模板第 10 节）：

把 AI 协同记录写成“可核验”的格式（建议直接复制下面小模板，填真实内容）：

记录 #（代码审计 / 文档完善）：

环节 2（推荐）：AI 辅助文档结构优化与内容补全
输入给 AI：

要求 AI 输出（结构化）：

1）缺口清单（按章节归类）

2）重排后的目录与每章必填项

3）需要补的截图/记录列表（逐条写“截图内容 + 命令/操作 + 预期证据字段”）

4）可直接粘贴的补充段落草稿（但必须标注需要你补的真实数据）

人工审计点：

  1. 命令一致：文档中的命令能在干净环境执行，不依赖“我本地才有”的路径
  2. 字段一致：输出字段名与文档/测试断言一致（trace_id、parse_trace_id 等）
  3. 证据一致：每个结论都有可复验证据，不靠口头解释
  4. 回归一致：修复后 Smoke Test 通过（或失败列表清楚且能定位环节）

导出前快速自检（避免被打回）：

  1. 代码审计：出示问题清单与修复闭环（以“作业（布置）”模板要求为准）。
  2. AI 协同：出示 AI 协同审计记录与人工审计结论（以“作业（布置）”模板要求为准）。

现场出示要求：只需打开你最终提交的 PDF；证据组织结构与抽查范围以“作业（布置）”的模板第 3–10 节为准（环境/API/输出契约/端到端与 Smoke Test/审计与修复闭环/文档完善/AI 记录）。

作业（布置）

本次为第 10 + 11 讲合并作业：只提交 1 个“Markdown 转 PDF”的交付文件，不收源码、不收额外附件。

提交要求（统一规范）：

  1. 文件命名（必须一致）：
  1. 文件格式：
  1. 证据呈现方式：
  1. 注意：

作业模板（Markdown 正文结构，复制后替换占位内容）：

  1. 封面信息
  1. 项目概述（对齐第 10 讲）
  1. 环境与运行（对齐第 10 讲，必须可复现）
  1. API 验证证据（对齐第 10 讲）
  1. Prompt 与输出契约（对齐第 10 讲）
  1. 代码审计报告（对齐第 11 讲）
  1. 修复闭环（对齐第 11 讲，≥2 个）
  1. 开发文档完善记录（对齐第 11 讲）
  1. AI 协同审计记录（对齐第 10 + 11 讲，至少 2 次）
  1. 附录（可选，但推荐）