# JobRadar · 职途雷达 JobRadar 是一套面向个人使用、以 Agent 为核心的智能岗位发现与决策系统。Agent 根据用户目标制定执行步骤，调用岗位采集、企业调查、规则筛选、评分和数据持久化工具，完成多步骤任务，并将过程、证据和结果展示在 WebUI 中。 > 当前项目处于基础骨架阶段，已完成 Django 工程初始化；岗位采集、企业研判、评分、异步任务和业务页面均在后续迭代范围内。 ## 项目目标 - 使用正规的 Agent 运行循环完成任务规划、工具调用、状态延续和结果输出。 - 通过独立站点工具采集授权范围内的岗位信息。 - 统一不同来源的岗位字段，并识别重复岗位和内容变化。 - 使用硬性规则优先排除明显不符合要求的岗位。 - 联网补充企业主体、企业性质和行业等信息，保留来源与查询时间。 - 按可配置权重计算岗位匹配分，输出推荐理由和风险提示。 - 提供适合个人使用的岗位管理、收藏、忽略和投递跟踪页面。 - 保留原始数据、规则版本和分析证据，使每项结论可以复核。 - 展示 Agent 的执行轨迹、工具调用、耗时、失败原因和人工确认节点，用于学习与项目展示。 ## 技术栈 | 分类 | 选型 | 当前状态 | | --- | --- | --- | | 开发语言 | Python 3.13 | 已配置 | | Web 框架 | Django 6.0.8 | 已配置 | | 开发与测试数据库 | SQLite | 第一阶段默认使用 | | 集成与生产数据库 | PostgreSQL | 集成验证可使用远程或本地实例，生产环境强制使用 | | 页面采集 | Playwright | 环境已安装，尚未接入 | | 普通请求 | HTTPX | 规划中 | | 异步任务 | Celery + Redis | 规划中 | | 定时调度 | Celery Beat | 规划中 | | Agent 运行时 | OpenAI Agents SDK（Python） | 规划中 | | 模型接口 | 多服务商预设 + OpenAI/Anthropic/Gemini 协议 | 配置基础已完成，真实调用规划中 | | Agent 输出 | Pydantic 结构化模型 | 规划中 | | 可观测性 | Agents SDK Tracing + 业务运行记录 | 规划中 | | Agent 评测 | 官方 Agent Evals 思路 + 本地评测集 | 规划中 | | 用户系统 | Django 内置认证 + 简化用户资料 | 规划中 | | WebUI | Django Admin + 自定义 Django 页面 | 认证、运行记录与 API 服务商配置已完成 | | 部署 | Docker Compose + Nginx/Caddy + HTTPS | 规划中 | 第一阶段优先采用 Django Admin 管理站点、规则、企业和任务数据，再为岗位浏览与决策流程开发自定义页面。出现明确的前后端分离需求后，再评估是否增加 Django REST Framework 和 Vue。 ## 当前目录 ```text JobRadar/ ├── JobRadar/ Django 项目配置与分环境 settings │ ├── asgi.py │ ├── settings/ │ │ ├── base.py │ │ ├── development.py │ │ ├── integration.py │ │ ├── production.py │ │ └── test.py │ ├── urls.py │ └── wsgi.py ├── docs/ 架构与实施文档 ├── templates/ 全局 Django 模板 ├── environment.yml Conda 环境定义 ├── manage.py Django 管理入口 └── README.md ``` 业务模块将随迭代逐步增加，暂定拆分为： ```text accounts/ 用户认证、个人配置与数据归属 jobs/ 岗位、岗位来源及状态跟踪 companies/ 企业主体及企业证据 crawlers/ 招聘网站采集适配器 screening/ 硬性筛选规则 ranking/ 权重评分 agent_runtime/ Agent 定义、运行上下文与编排入口 agent_tools/ 采集、检索、筛选、评分和持久化工具 evals/ Agent 行为评测用例与结果 task_center/ 采集、分析与调度任务 audit/ 日志、证据与版本追踪 ``` 详细边界参见 [架构设计](docs/architecture.md)，Agent 的目标、工具和状态约定参见 [Agent 契约](docs/agent-contract.md)，开发顺序参见 [实施路线图](docs/roadmap.md)。 ## AI开发方式 JobRadar采用“阶段目标驱动、AI直接实现”的开发方式： 1. 用户确认当前阶段目标、业务边界和验收重点。 2. AI先检查仓库现状，给出修改方案和涉及文件。 3. AI直接生成或修改代码、迁移、配置、测试与必要文档。 4. AI执行静态检查、自动化测试和安全检查，并如实报告未覆盖项。 5. 用户根据可运行结果和页面效果进行业务验收。 6. 当前阶段稳定后，再进入下一阶段或扩展更多工具。 实现应保持增量、小步、可验证。不会为了展示一次性生成所有未来模块，也不会将尚未运行验证的规划描述为已完成功能。详细约定参见 [AI开发约定](docs/development-guide.md)。 ## 本地运行 ### 1. 创建或更新 Conda 环境 如果本机还没有 `JobRadar` 环境： ```powershell conda env create -f environment.yml ``` 如果环境已经存在： ```powershell conda env update -n JobRadar -f environment.yml --prune ``` 激活环境： ```powershell conda activate JobRadar ``` ### 2. 检查数据库迁移 当前默认使用项目目录中的 SQLite 数据库： ```powershell python manage.py migrate ``` ### 3. 创建本地管理员 ```powershell python manage.py createsuperuser ``` ### 4. 启动开发服务 ```powershell python manage.py runserver ``` 访问地址： - 管理后台： ### 5. 安装 Playwright 浏览器 首次开发采集模块时执行： ```powershell python -m playwright install chromium ``` 浏览器文件不应提交到仓库。 ## 配置原则 - 本地开发密钥、数据库密码、招聘网站 Cookie 和模型 API Key 不得提交到 Git。 - 项目使用 `JobRadar/settings/` 分离开发、测试、集成和生产配置；部署时必须显式选择生产配置。 - 第一阶段本地开发和自动化测试默认使用 SQLite，数据库文件不得提交到版本库。 - PostgreSQL 通过环境变量按需启用；阶段结束前至少完成一次空库迁移和核心模型测试。 - 远程 PostgreSQL 必须使用 TLS、项目专属数据库和低权限账号，自动化测试不得连接生产库。 - 生产环境必须使用 PostgreSQL，不允许静默回退到 SQLite。 - 采集器必须设置并发、频率、超时和指数退避，不能绕过验证码、登录保护或访问控制。 - 企业性质及 AI 判断必须保存来源、判断时间和置信度；信息不足时应标记为待人工复核。 ### 模型服务商配置 登录后可访问 `/runs/providers/` 配置模型服务商。OpenAI、Claude、DeepSeek、Gemini、阿里云百炼、智谱 AI、硅基流动及部分 OpenAI 兼容平台已提供固定端点预设；Azure OpenAI、AWS Bedrock 等需要部署或 IAM 参数的平台目前仅展示目录状态。 页面保存 API Key 前必须配置独立主密钥： ```powershell $env:MODEL_API_KEY_ENCRYPTION_KEY="请使用至少32个字符的高强度随机值" ``` 该主密钥不得提交到仓库。遗失或直接替换主密钥会导致已有 API Key 无法解密；正式轮换前必须实现密文重加密流程。 ## 用户系统 系统面向公网部署，因此第一阶段即接入用户认证，但不设计复杂的角色权限体系： - 使用 Django 内置用户、密码哈希、Session 和登录保护能力。 - 普通用户登录后只能访问自己的搜索任务、筛选配置、岗位状态和个人画像。 - 管理员使用 Django Admin 维护站点适配器、系统任务和异常数据。 - 第一阶段只区分普通用户与管理员，不增加角色表、权限组、组织机构或审批流。 - 业务数据必须记录所属用户，查询和任务执行时统一校验数据归属。 - 默认关闭公开注册，由管理员创建账号；确需开放注册时再增加邮箱验证、验证码和频率限制。 ## 公网部署要求 - Django 由生产级 WSGI/ASGI 服务运行，不能使用 `manage.py runserver` 对外提供服务。 - 使用 Nginx 或 Caddy 作为反向代理，并强制启用 HTTPS。 - 正确配置 `ALLOWED_HOSTS`、可信 CSRF 来源、安全 Cookie 和代理转发头。 - PostgreSQL 和 Redis 仅在容器私有网络中开放，不映射到公网。 - 登录、注册、密码重置和耗时接口应设置频率限制与异常审计。 - 密钥、数据库密码、网站 Cookie 和模型 API Key通过部署平台密钥或受保护的环境配置注入。 - 定期备份数据库，并验证备份恢复流程。 ## 开发约定 - 一个招聘网站对应一个采集适配器，禁止把站点特有解析逻辑写入公共业务模块。 - Agent 通过类型明确的工具完成外部操作，不在提示词中伪造浏览、查询或入库结果。 - 第一版只实现一个岗位研究 Agent；只有单 Agent 难以维持明确职责时才增加专家 Agent 和 handoff。 - 涉及持久化或外部副作用的工具必须边界窄、可审计、可重试。 - 高风险或不可逆操作必须设置人工确认；第一版不允许 Agent 自动投递简历或联系招聘人员。 - 原始数据与标准化数据分开保存，避免解析规则变化后无法追溯。 - 先执行确定性筛选，再调用联网服务和大模型，降低成本与误判范围。 - 规则筛选和权重计算作为确定性工具提供给 Agent，最终分数不能由模型随意生成。 - 采集、企业补全和 AI 分析任务必须可重复执行，并通过唯一约束或幂等键防止重复入库。 - 重要判断应包含证据，不以模型生成的自然语言作为唯一依据。 ## 明确不采用的捷径 - 不把一次普通的大模型请求包装成 Agent；必须存在真实的运行循环、工具调用、状态和轨迹。 - 不用 LangChain 等兼容层统一不同模型或 Agent 框架，优先直接学习 OpenAI Agents SDK 的原生能力。 - 当前业务没有知识库检索需求，不引入 pgvector、独立向量数据库或为了展示而搭建 RAG。 - 不一开始拆成多 Agent；先用一个 Agent 验证完整闭环，再依据评测结果演进。 ## 验证命令 ```powershell python manage.py check python manage.py test ``` 涉及数据模型变更时，还应检查是否遗漏迁移文件： ```powershell python manage.py makemigrations --check --dry-run ``` ## 合规说明 JobRadar 仅用于个人岗位信息整理与求职辅助。使用前应确认目标网站的服务条款、数据授权范围和访问频率限制。项目不以绕过验证码、风控、登录限制或其他技术保护措施为目标，也不应自动投递简历或自动联系招聘人员。 ## 项目状态 当前版本：`0.1.0-dev` 当前阶段：第一阶段工程基线及 SDK 测试替身编排闭环已经落地，正在完成质量工具环境同步、生产配置检查、页面人工验收和 PostgreSQL 集成验证；通过全部验收后进入第二阶段最小 Agent 闭环及真实 Agents SDK 接入。