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

docs/architecture.md

@@ -2,115 +2,116 @@
 
 ## 设计原则
 
-JobRadar 第一阶段采用模块化单体架构。Django 负责业务模型、管理后台、自定义页面和任务入口；耗时的浏览器采集、企业信息补全和 AI 分析由异步 Worker 执行。各业务模块在代码层隔离，但共享 PostgreSQL 数据库，避免在个人项目初期引入微服务通信和部署成本。
+JobRadar 采用 Agent 原生的模块化单体架构。Django 负责公网产品外壳、用户系统、业务数据和运行记录；OpenAI Agents SDK 负责 Agent 循环、工具调用、结构化输出、运行状态和追踪；Celery Worker 承载耗时运行。各模块共享 PostgreSQL，避免为了展示效果提前拆分微服务。
 
 ## 目标架构
 
 ```mermaid
 flowchart LR
     USER["公网用户"] --> PROXY["Nginx / Caddy 与 HTTPS"]
-    PROXY --> WEB["Django 登录、Admin 与岗位工作台"]
-    WEB --> APP["Django 业务应用"]
+    PROXY --> WEB["Django 登录与 Agent 工作台"]
+    WEB --> APP["Django 业务与运行管理"]
     APP --> DB[("PostgreSQL")]
-    APP --> REDIS["Redis"]
+    APP --> REDIS["Redis 任务队列"]
     BEAT["Celery Beat"] --> REDIS
-    REDIS --> WORKER["Celery Worker"]
-    WORKER --> COLLECT["Playwright / HTTPX 采集"]
-    WORKER --> ENRICH["企业信息联网补全"]
-    WORKER --> AI["LLM 结构化分析"]
-    COLLECT --> DB
-    ENRICH --> DB
-    AI --> DB
+    REDIS --> WORKER["Celery Agent Worker"]
+    WORKER --> RUNNER["Agents SDK Runner"]
+    RUNNER --> AGENT["岗位研究 Agent"]
+    AGENT --> TOOLS["类型化 Function Tools"]
+    TOOLS --> COLLECT["Playwright / HTTPX"]
+    TOOLS --> ENRICH["企业信息与联网调查"]
+    TOOLS --> RULES["规则筛选与权重计算"]
+    TOOLS --> DB
+    RUNNER --> TRACE["Tracing 与运行事件"]
 ```
 
+## Agent 定位
+
+Agent 不是对岗位描述进行一次总结的接口，而是任务执行主体。一次完整运行需要接收目标和边界、自主选择工具、根据工具结果继续调查，并在证据不足或涉及敏感操作时暂停，最终输出结构化结果和完整轨迹。
+
+第一版只设置一个“岗位研究 Agent”。采集器、企业查询、评分器和数据库不是独立 Agent，而是 Agent 可以调用的确定性工具。只有评测证明单 Agent 在职责或指令复杂度上不可维护时，才拆分专家 Agent 并使用正式 handoff。
+
+## Agent 运行边界
+
+- 使用 OpenAI Agents SDK 的 `Agent` 和 `Runner` 实现运行循环，不自行模拟工具调用循环。
+- 使用 `function_tool` 暴露业务能力，输入和输出采用明确的数据模型。
+- Django 请求只创建任务；长时间 Agent Run 由 Celery Worker 执行。
+- 运行上下文携带用户、任务、规则版本和数据库会话边界，不把敏感凭据写入提示词。
+- Agent 最终输出使用结构化模型校验，数据库写入仍通过受控工具执行。
+- 保存 run、turn、tool call、tool result、trace、耗时、token 用量、异常和人工确认状态。
+- 第一版不使用 SandboxAgent；业务只需受控网络和数据库工具，不需要开放 Shell 或任意文件执行能力。
+
 ## 用户与权限边界
 
-系统支持公网访问，第一阶段采用简化的用户体系：
+- 使用 Django 内置认证、Session 和密码管理能力。
+- 普通用户拥有个人画像、搜索任务、规则、Agent Run 和岗位操作记录。
+- 用户私有数据通过所属用户字段隔离，工具执行前统一校验数据归属。
+- 管理员通过 Django Admin 维护全局站点配置、工具开关和异常数据。
+- 第一阶段仅区分普通用户与管理员，不建设复杂 RBAC。
+- 默认由管理员创建账号并关闭公开注册。
 
-- 直接使用 Django 内置用户、认证、Session 和密码管理能力。
-- 普通用户拥有个人画像、搜索任务、筛选规则、评分配置和岗位操作记录。
-- 所有用户私有业务表通过所属用户字段隔离，服务层和查询层统一限制当前用户的数据范围。
-- 管理员通过 Django Admin 维护全局站点配置、采集状态和异常数据。
-- 第一阶段仅区分普通用户与管理员，不建设 RBAC、组织机构、岗位角色和审批授权模型。
-- 默认由管理员创建账号并关闭公开注册；开放注册属于后续独立功能。
+## Agent 处理链路
 
-即使初期实际只有一个账号，数据模型仍保留用户归属，避免未来增加账号时重新改造所有核心表。
-
-## 处理链路
-
-1. 用户配置目标网站、关键词、地区、硬性条件和评分权重。
-2. 调度器创建采集批次，站点适配器获取并保存原始岗位记录。
-3. 标准化模块统一岗位、公司、薪资、经验和地点字段。
-4. 去重模块根据来源岗位编号、内容指纹和标准化字段建立岗位关系。
-5. 筛选模块先执行可确定判断的硬规则，并记录通过、淘汰或待确认原因。
-6. 企业补全模块查询可信来源，保存企业主体、性质、证据和置信度。
-7. AI 模块对通过初筛的岗位进行技能、职责、风险和匹配度分析。
-8. 评分模块根据固定公式生成最终分数，并保存评分配置版本。
-9. 用户在岗位工作台中收藏、忽略或更新投递状态。
+1. 用户提交岗位研究目标，Django 创建 Agent Run 并投递异步任务。
+2. Agent 读取用户画像、目标网站、硬性条件、评分权重和运行预算。
+3. Agent 调用搜索与采集工具获取候选岗位，工具保存原始证据。
+4. Agent 调用标准化、去重和硬规则工具，剔除确定不符合的岗位。
+5. Agent 按需调用企业查询和联网调查工具补足证据。
+6. Agent 调用结构化分析及确定性评分工具，得到维度分数和风险项。
+7. 证据冲突或置信度不足时标记待人工复核，不强行下结论。
+8. Agent 输出研究报告，持久化工具保存结果、引用和运行状态。
+9. WebUI 展示推荐结果、Agent 轨迹、工具调用和失败节点。
 
 ## 模块边界
 
-### 采集模块
+### Agent 运行模块
+
+- 定义 instructions、运行上下文、工具集合和结构化输出契约。
+- 控制最大轮次、时间预算、工具预算和失败恢复策略。
+- 使用 SDK tracing 观察运行，并同步关键事件到本地数据库。
+- 通过 guardrail 和人工确认限制高风险行为。
+- 可以按内容和分析版本复用结果，但不引入向量检索兼容层。
+
+### 工具层
+
+- 一个工具只承担一种可描述、可测试的业务能力。
+- 工具负责真实外部操作，Agent 不得声称执行未发生的查询或写入。
+- 写工具必须幂等，记录调用来源、输入摘要、输出摘要和异常。
+- 工具只返回下一步所需数据，避免把敏感信息放入模型上下文。
+
+### 采集与企业研究工具
 
 - 优先使用网站允许访问的接口或普通 HTTP 请求，动态页面才使用 Playwright。
-- 每个网站独立实现适配器，并输出统一的原始岗位数据对象。
-- 负责限流、超时、重试和采集状态，不负责岗位评分。
-- 页面变更导致解析失败时，应保留错误证据并暂停对应适配器。
+- 每个网站独立实现适配器，并输出统一的原始岗位对象。
+- 企业结论保存来源、证据摘要、获取时间和置信度。
+- 多来源冲突、主体不明确或置信度不足时请求人工复核。
 
-### 标准化与去重模块
-
-- 原始数据只追加或生成新版本，不被标准化结果覆盖。
-- 同站唯一键建议为“站点编号 + 来源岗位编号”。
-- 跨站重复判断结合公司标准名、岗位名、地点、薪资和内容指纹。
-- 跨站重复岗位建立关联，不直接物理删除来源记录。
-
-### 企业补全模块
-
-- 按企业标准名称或统一社会信用代码识别主体。
-- 结论至少保存来源地址、证据摘要、获取时间和置信度。
-- 多来源冲突、主体不明确或置信度不足时进入人工复核。
-- 人工确认结果优先级高于自动判断，但不得删除历史证据。
-
-### AI 分析模块
-
-- 输入为标准化岗位、个人画像和必要证据，不直接使用未经清洗的整页内容。
-- 输出必须通过结构化模型校验，不接受无法解析的自由文本作为业务结果。
-- 记录模型名称、提示词版本、输入摘要和分析时间。
-- 相同内容与同一分析版本应优先复用缓存结果。
-
-### 评分模块
+### 规则与评分工具
 
 - 硬性条件和最终加权公式由确定性代码执行。
-- 每个评分维度保留原始分、权重、加权分和判断依据。
+- 每个维度保存原始分、权重、加权分和判断依据。
 - 权重或规则变化时创建新版本，历史结果仍可回溯。
-- 风险扣分与正向评分分开保存，避免结果无法解释。
+- Agent 不能绕过规则工具或自行生成最终分数。
 
 ## 数据边界
 
-第一阶段核心实体包括：
-
-- 招聘网站及站点配置
-- 搜索任务与采集批次
-- 原始岗位记录与标准化岗位
-- 企业主体与企业证据
-- 筛选规则、规则版本和筛选结果
-- 评分配置、评分结果和 AI 分析记录
-- 收藏、忽略、投递和面试状态
-- 任务日志与人工复核记录
-
-具体字段应在首个目标网站和筛选规则明确后再落地，避免提前设计大量无法验证的字段。
+- 用户、个人画像及数据归属
+- 招聘网站、搜索任务与采集批次
+- 原始岗位、标准化岗位与企业证据
+- 筛选规则、评分配置及其版本
+- Agent Run、运行事件、工具调用和结构化输出
+- Agent 指令版本、工具版本、模型配置和评测结果
+- 收藏、忽略、投递、面试和人工复核记录
 
 ## 部署边界
 
-系统目标部署到公网。目标运行单元为：
-
 ```text
 web       Django Web 服务
-worker    Celery Worker
+worker    Celery Agent Worker 与 Agents SDK Runtime
 beat      Celery 定时调度
 postgres  PostgreSQL
 redis     Redis
 proxy     Nginx 或 Caddy 反向代理及 HTTPS 终止
 ```
 
-公网只开放反向代理的 HTTP/HTTPS 端口。Django、PostgreSQL 和 Redis 位于容器私有网络；Django 使用生产级 WSGI/ASGI 服务运行，不使用开发服务器对外提供服务。部署时必须配置 HTTPS、安全 Cookie、`ALLOWED_HOSTS`、可信 CSRF 来源、登录限流、密钥注入、日志审计和数据库备份。
+公网只开放反向代理的 HTTP/HTTPS 端口。Django、PostgreSQL 和 Redis 位于容器私有网络，并配置 HTTPS、安全 Cookie、可信来源、登录限流、密钥注入、日志审计和数据库备份。