docs(course): 建立Agent学习路线并新增第一课

docs/roadmap.md

@@ -1,95 +1,143 @@
 # JobRadar 实施路线图
 
-## 阶段一：基础工程
+## 推进规则
 
-目标是建立可持续开发的 Django 项目基线。
+本路线图用于确定学习顺序，不代表一次性生成所有代码。每个阶段继续拆成若干课，每次只开始当前一课：
 
-- [x] 初始化 Django 项目。
-- [x] 创建 Conda 环境。
-- [x] 创建本地和远程 Git 仓库。
-- [x] 补充项目、架构和路线图文档。
-- [ ] 拆分开发、测试和生产配置。
-- [ ] 将密钥及本地配置移出版本库。
-- [ ] 接入 Django 用户认证并建立用户资料模型。
-- [ ] 为搜索任务、筛选配置和岗位操作增加用户归属。
-- [ ] 默认关闭公开注册，只保留管理员创建账号入口。
+- 开课时先讲解原理、Agent职责和本课代码边界。
+- 提供可运行的参考代码，但由学习者手动写入项目。
+- 学习者提交实现后进行代码检查和运行验证。
+- 当前课验收通过后，才准备下一课。
+- 不提前创建后续课程的业务代码或空目录。
+- 阶段结束时安排回顾、评测和一个可展示的阶段成果。
+
+## 阶段一：Agent 工程基线
+
+建议课程：
+
+1. Django项目配置与开发/生产环境拆分。
+2. Django用户系统与用户数据归属。
+3. PostgreSQL迁移与Agent运行数据模型。
+4. OpenAI Agents SDK最小Agent与Runner。
+5. Agent Run、运行事件与工具调用持久化。
+
+- [x] 初始化 Django 项目、Conda 环境和 Git 仓库。
+- [x] 补充项目、架构、Agent 契约和路线图文档。
+- [ ] 拆分开发、测试和生产配置，将密钥移出版本库。
+- [ ] 接入 Django 用户认证和用户资料模型。
 - [ ] 接入 PostgreSQL 并建立迁移基线。
+- [ ] 接入 OpenAI Agents SDK。
+- [ ] 建立 Agent Run、运行事件、工具调用和人工确认模型。
 - [ ] 增加统一日志、测试和代码质量工具。
 
-## 阶段二：单站采集闭环
+## 阶段二：最小 Agent 闭环
 
-目标是稳定采集一个明确授权范围内的招聘网站。
+建议课程：
 
-- [ ] 确认首个目标网站及其服务条款和访问边界。
-- [ ] 定义站点适配器协议和原始岗位数据结构。
-- [ ] 实现搜索任务、采集批次和原始岗位模型。
-- [ ] 实现首个站点适配器。
+1. Function Tool原理及第一个只读工具。
+2. Pydantic结构化输入与输出。
+3. 多工具选择和Agent运行循环。
+4. 运行预算、超时、异常与人工确认。
+5. Agent轨迹页面和最小评测集。
+
+- [ ] 定义岗位研究 Agent 的 instructions、输入、输出、工具、状态和人工确认点。
+- [ ] 使用 Agents SDK 实现一个 Agent 和 Runner 入口。
+- [ ] 实现候选岗位查询、规则筛选和结果保存三个最小 Function Tool。
+- [ ] 设置最大轮次、超时和工具调用预算。
+- [ ] 保存工具调用、结果摘要、最终输出和 trace 标识。
+- [ ] 在 WebUI 展示一次完整运行，而不只展示最终回答。
+- [ ] 建立最小评测集，覆盖正常结果、证据不足、工具失败和禁止操作。
+
+验收条件：Agent 能自主选择并调用真实工具，输出结构化结果；页面可以查看工具轨迹，评测能识别没有调用必要工具的伪结果。
+
+## 阶段三：单站采集与筛选
+
+建议课程：
+
+1. 招聘网站适配器与工具边界。
+2. HTTPX与Playwright采集。
+3. 原始数据、标准化与幂等入库。
+4. 硬性筛选工具和Agent调用。
+5. 单站采集阶段项目。
+
+- [ ] 确认首个招聘网站的服务条款和访问边界。
+- [ ] 定义站点适配器协议和原始岗位结构。
+- [ ] 实现首个站点适配器及采集工具。
 - [ ] 增加限流、超时、重试和失败日志。
-- [ ] 完成来源岗位编号去重和内容变更识别。
-- [ ] 在 Django Admin 中提供任务和原始数据管理能力。
-
-验收条件：可以手动运行一次采集，查看新增、更新、重复和失败数量，并从标准化岗位追溯到原始来源。
-
-## 阶段三：岗位标准化与筛选
-
-目标是用确定性规则减少无效岗位。
-
 - [ ] 定义岗位、企业和岗位来源模型。
 - [ ] 标准化岗位名、地点、薪资、经验和学历。
-- [ ] 建立排除词、黑名单和硬性筛选规则。
-- [ ] 输出通过、淘汰和待确认结果及具体原因。
-- [ ] 实现岗位列表、详情、收藏、忽略和投递状态。
-- [ ] 保存规则版本，支持重新筛选历史岗位。
+- [ ] 完成来源岗位编号去重和内容变化识别。
+- [ ] 建立排除词、黑名单和硬性筛选工具。
+- [ ] 实现岗位列表、详情和个人处理状态。
 
-验收条件：不调用大模型也能稳定过滤明确不符合要求的岗位，并解释每条淘汰原因。
+验收条件：Agent 通过真实工具采集一个网站，所有岗位均可追溯到原始来源，确定性规则能解释淘汰原因。
 
-## 阶段四：企业联网补全
+## 阶段四：企业联网研究
 
-目标是可靠判断企业主体和企业性质。
+建议课程：
+
+1. 企业研究任务拆解和证据模型。
+2. 联网搜索工具与来源可信度。
+3. 企业主体归一化和证据冲突。
+4. 人工复核与可恢复运行。
 
 - [ ] 确定合法、稳定的企业信息来源。
 - [ ] 建立企业别名、标准主体和证据模型。
-- [ ] 保存企业性质、行业、集团、来源和置信度。
-- [ ] 实现多来源冲突检测和待复核队列。
-- [ ] 支持人工确认，并保留自动判断历史。
+- [ ] 实现企业研究工具，保存来源、时间和置信度。
+- [ ] 实现多来源冲突检测和人工复核队列。
+- [ ] 保留自动判断和人工确认历史。
 
-验收条件：企业性质结论包含可访问的来源和查询时间，无法确认的企业不会被强行分类。
+验收条件：Agent 不会在证据不足时强行分类，企业结论包含可访问来源和查询时间。
 
-## 阶段五：AI 分析与权重评分
+## 阶段五：评分、护栏与评测
 
-目标是形成可解释的岗位推荐结果。
+建议课程：
+
+1. 个人画像和匹配分析契约。
+2. 确定性评分工具。
+3. Guardrail与越权防护。
+4. Agent行为评测和回归用例。
+5. Trace分析和提示词迭代。
 
 - [ ] 定义个人岗位画像和技能偏好。
-- [ ] 定义结构化 AI 输出模型。
-- [ ] 提取技能、职责、隐含条件和风险点。
-- [ ] 实现可配置评分维度及权重校验。
-- [ ] 保存维度分数、风险扣分、理由和分析版本。
-- [ ] 对相同内容建立缓存，控制调用成本。
+- [ ] 完善 Agent 结构化输出模型和运行状态。
+- [ ] 实现匹配分析工具与确定性评分工具。
+- [ ] 保存维度分数、风险扣分、理由和版本。
+- [ ] 增加输入/输出 guardrail 和人工确认节点。
+- [ ] 建立工具选择、证据引用、拒绝越权和故障恢复评测。
+- [ ] 使用 trace 分析失败运行并形成回归用例。
 
-验收条件：每个总分都可以分解到评分维度、权重和证据，大模型不能越过硬性规则直接改变结果。
+验收条件：每个总分都能分解到权重和证据；Agent 必须调用必要工具，不得编造外部事实或越过硬规则。
 
-## 阶段六：调度、通知与扩站
+## 阶段六：调度、公网部署与展示
 
-目标是让系统长期稳定运行。
+建议课程：
+
+1. Celery异步Agent Run。
+2. 定时任务、幂等和故障恢复。
+3. Agent工作台与执行过程展示。
+4. Docker Compose和生产配置。
+5. HTTPS公网部署与最终演示。
 
 - [ ] 接入 Celery、Redis 和 Celery Beat。
-- [ ] 实现任务幂等、指数退避和失败恢复。
-- [ ] 增加任务中心与运行状态展示。
+- [ ] 实现运行幂等、指数退避、暂停和恢复。
+- [ ] 完成 Agent 任务中心与实时运行状态展示。
 - [ ] 增加高分新岗位通知。
-- [ ] 增加第二个站点适配器，验证扩展边界。
-- [ ] 增加备份、清理和恢复机制。
-- [ ] 使用 Nginx 或 Caddy、生产级应用服务器和 HTTPS 完成公网部署。
-- [ ] 增加安全 Cookie、CSRF、登录限流和安全响应头检查。
+- [ ] 增加第二个站点工具，验证扩展边界。
+- [ ] 使用 Nginx/Caddy、生产级应用服务器和 HTTPS 部署。
+- [ ] 增加安全响应头、登录限流和数据库备份。
+- [ ] 整理演示用 Agent 轨迹、评测结果和架构说明。
 
-验收条件：定时任务连续运行时不会重复创建岗位，单个站点失败不会影响其他任务，异常可以从日志和任务记录中定位。
+验收条件：系统可以在公网安全运行，用户能同时查看岗位结果与 Agent 执行过程，站点故障不会破坏其他运行。
 
 ## 第一轮开发前待确认
 
-1. 首个目标招聘网站及允许使用的访问方式。
-2. 搜索岗位、城市、薪资、经验和学历范围。
-3. 必须包含与必须排除的关键词。
+1. 首个招聘网站及允许使用的访问方式。
+2. 岗位、城市、薪资、经验和学历范围。
+3. 必须包含和必须排除的关键词。
 4. 企业性质、行业和公司规模偏好。
 5. 评分维度及初始权重。
-6. 企业信息数据源和大模型服务方式。
-7. 运行频率、单次采集页数和通知渠道。
-8. 公网域名、部署服务器和 HTTPS 证书管理方式。
+6. 企业信息数据源。
+7. OpenAI 模型、调用预算及单次运行上限。
+8. 运行频率、单次岗位数量和通知渠道。
+9. 公网域名、服务器和 HTTPS 证书管理方式。