JobRadar/docs/learning-guide.md

JobRadar 学习协作说明

项目定位

JobRadar不只是需要交付的岗位系统，也是用于系统学习正规Agent开发的实战项目。学习目标包括Agents SDK运行循环、工具设计、状态管理、人工确认、可观测性、评测、公网Web应用和工程化部署。

默认协作方式

每次只推进一课，流程如下：

1. 回顾上一课成果和遗留问题。
2. 说明本课完成后能够做什么。
3. 解释新概念是什么、为什么需要以及在JobRadar中的位置。
4. 使用Java、Spring或常见后端设计进行必要对照。
5. 给出本课完整参考代码，并逐段解释执行顺序和设计原因。
6. 明确代码应该写入哪个文件以及如何运行。
7. 给出预期结果、常见错误、调试方法和验收标准。
8. 学习者手动完成代码。
9. 对学习者代码进行检查，不直接覆盖已有实现。
10. 当前课通过后再继续下一课。

每课内容结构

每课原则上包含：

• 本课目标
• 前置知识
• 架构位置
• 核心原理
• Java或Spring对照
• 完整参考代码
• 关键代码解析
• 手动实现步骤
• 运行命令与预期结果
• 常见错误与排查方法
• 课堂练习
• 自检清单
• 验收标准
• 本课小结

代码边界

• 默认由学习者手动编写业务代码。
• 我提供参考代码、解释、提示、测试思路和审查反馈。
• 未经明确要求，不直接向JobRadar写入本课业务实现。
• 不一次性生成未来阶段代码，不提前制造空模块。
• 不覆盖学习者已有实现；发现问题时先说明原因和修正方案。
• 用户明确要求代为修改时，先说明方案、涉及文件和预期结果，再执行改动。

练习约定

如果后续为课程创建练习文件，练习文件只包含注释形式的题目、操作提示、预期结果、自检项和验收标准，不包含导入语句、函数骨架、pass、测试数据、答案或运行记录。

参考答案与练习文件分离。学习者完成代码后，优先基于学习者实现进行讲解，而不是用参考答案覆盖。

验收方式

每课至少验证：

• 代码能够在JobRadar Conda环境中运行。
• Django系统检查或对应测试通过。
• 行为与本课预期结果一致。
• Agent工具真实执行，没有用自然语言伪造结果。
• 数据写入具备用户归属、幂等和审计边界。
• 密钥、Cookie和本地配置没有进入Git。
• 学习者能够说明关键代码为什么这样设计。

涉及Agent的课程还需要检查工具调用、结构化输出、trace、失败路径和人工确认边界，不能只检查最终文本是否看起来正确。

教学深度

学习者已有Java和数据库基础，因此不重复教授变量、类、SQL、事务等通用概念。课程重点解释：

• Python与Java在语言和工程组织上的差异。
• Django与Spring Boot在请求处理、ORM、配置和用户体系上的差异。
• Agents SDK与普通Service编排、工作流引擎及传统定时任务的差异。
• Agent何时自主决策，何时必须交给确定性工具或人工确认。
• 如何通过trace和eval判断一个Agent是否真正可靠。

当前起点

第一课Django项目配置与开发/生产环境拆分已经创建。当前应阅读讲义、参考完整示例，然后手动拆分项目配置；完成后执行课程验收命令并提交代码供检查。