iknowkungfubar/freelance-lead-gen
GitHub: iknowkungfubar/freelance-lead-gen
一款自动化自由职业线索发现、AI 评分筛选与个性化联系草稿生成的接包辅助工具，内置完整的人工审查工作流。
Stars: 1 | Forks: 0
# 自由职业 Lead Gen
**Freelance Lead Gen** 自动化发现 Upwork、LinkedIn、Freelancer 和各大求职板上的自由职业及合同机会。它结合基于规则的评分和 LLM 驱动的分析来筛选线索，并生成带有反 AI 检测质量门禁的个性化联系草稿。在执行任何操作之前，所有内容都会呈现在终端 UI 中供人工审查。
## 快速入门
### 1. 获取 API Key
本系统使用 LLM (AI) 来筛选线索并生成联系草稿。
您需要从受支持的提供商处获取 API key：
- **[OpenCode](https://opencode.ai)** （推荐） — 10 美元免费额度，无需订阅
- **OpenAI** — 标准 API key
- 任何兼容 OpenAI 的提供商
### 2. 一键启动 (Docker)
```
docker run -p 8080:8080 -e LLM_API_KEY=*** ghcr.io/iknowkungfubar/freelance-lead-gen
```
然后打开 http://localhost:8080 查看健康状态。
### 3. 快速启动向导 (Python)
```
pip install freelance-lead-gen
freelance-lead-gen quickstart
```
### 4. 手动设置
将 `.env.example` 复制为 `.env`，填入您的 API key，然后：
```
freelance-lead-gen init
freelance-lead-gen discover --dry-run
freelance-lead-gen serve
```
### 5. 平台凭证
为了从 Upwork、LinkedIn 和 Freelancer 抓取机会，系统需要使用您的账户凭证登录每个平台。
- 您需要在每个想要监控的平台上拥有一个**免费账户**
- 浏览器自动化会在发现过程中使用您的凭证自动登录
- 凭证**本地**存储在 `.env` 中，除平台本身外绝不发送至任何其他地方
将您的凭证添加到 `.env` 中：
```
UPWORK_USERNAME=your_email@example.com
UPWORK_PASSWORD=your_password
LINKEDIN_USERNAME=your_email@example.com
LINKEDIN_PASSWORD=your_password
FREELANCER_USERNAME=your_email@example.com
FREELANCER_PASSWORD=your_password
```
## 功能特性
- **多平台发现** — 自动抓取 Upwork、LinkedIn、Freelancer 以及可配置的求职板，并使用针对特定平台的反机器人配置
- **AI 驱动的资格审核** — 结合基于规则的评分和 AI 驱动的技能/职位/预算分析，并进行等级划分 (HIGH / POTENTIAL / LOW)
- **个性化联系** — 生成量身定制的提案草稿，并带有反 AI 检测质量门禁，以确保语言自然
- **验证 pipeline** — 对每份草稿进行可读性评分、禁用短语扫描、AI 标记检测和结构检查
- **HITL (Human-in-the-Loop)** — 在终端 UI 中，所有联系草稿在提交前都需要经过人工审查和批准
- **隐身浏览器自动化** — 指纹轮换、模拟人类鼠标移动、高斯抖动延迟，以及可选的 `playwright-stealth` 集成，以避免被平台检测
- **可配置的调度** — 基于 APScheduler 的定期发现运行，支持可配置的时间间隔和每日上限
- **目标每天 50 条线索** — 旨在每天处理来自不同搜索查询的多达 50 条合格线索
- **丰富的终端 UI** — 使用 Textual 构建的仪表板、线索列表、详细视图、内容编辑器和审查队列
- **无自主提交** — 代理负责发现、筛选、起草和验证 — 但绝不提交。所有出站操作必须通过 HITL 门禁。
## 架构
系统采用分阶段的 pipeline 架构。机会按顺序流经每个阶段，并在每个阶段持久化到 SQLite。
```
graph LR
subgraph Discovery
DA[Discovery Agent]
EX[Platform Extractors]
MB[Managed Browser]
end
subgraph Filtering
FP[Filtering Pipeline]
PM[Profile Matcher]
LLM1[LLM Scorer]
end
subgraph Personalization
PA[Personalization Agent]
LLM2[LLM Generator]
AQ[Anti-AI Quality Gate]
end
subgraph Verification
VA[Verification Agent]
end
subgraph HITL
TUI[Terminal UI / Review Queue]
HUMAN[Human Reviewer]
end
DA --> FP
FP --> PA
PA --> VA
VA --> TUI
TUI -->|approve/reject| HUMAN
EX --> DA
MB --> EX
PM --> FP
LLM1 --> FP
LLM2 --> PA
AQ --> PA
```
**数据流：** 原始线索 → 结构化机会 → 评分与分层 → 个性化草稿 → 已验证草稿 → 人工审查 → 批准提交（手动）。
## 快速开始
最快的上手方式是交互式**快速启动向导**：
```
pip install freelance-lead-gen
freelance-lead-gen quickstart
```
向导将引导您在 2 分钟内完成 API key 和平台凭证的设置，
随后您就可以开始了：
```
freelance-lead-gen discover # find opportunities
freelance-lead-gen review # review and approve drafts
```
### 手动设置（替代方案）
用于开发或需要完全控制时，请克隆存储库并手动设置：
```
# Clone the repository
git clone https://github.com/iknowkungfubar/freelance-lead-gen.git
cd freelance-lead-gen
# 使用 uv 安装（推荐）
uv venv
source .venv/bin/activate
uv sync
# 安装 Playwright browsers
playwright install chromium
# 复制并编辑配置
cp .env.example .env
# 编辑 .env 并填入你的 LLM API key 和平台凭据
# 初始化数据库
freelance-lead-gen init
# 运行 discovery（可选 — 按你的配置进行 enrich）
freelance-lead-gen discover
# 启动 review TUI
freelance-lead-gen review
# 或运行完整 pipeline
freelance-lead-gen pipeline
```
## 配置
所有配置均通过环境变量或项目根目录下的 `.env` 文件进行管理。将 `.env.example` 复制为 `.env` 并填入您的值。
### LLM
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `LLM_PROVIDER` | `opencode` | 提供商名称（用于日志记录/路由） |
| `LLM_MODEL` | `deepseek-v4-flash` | 模型标识符 |
| `LLM_BASE_URL` | `https://opencode.ai/zen/go/v1` | API 基础 URL (兼容 OpenAI) |
| `LLM_API_KEY` | — | API key |
| `LLM_MAX_RETRIES` | `3` | 最大 API 调用重试次数 |
| `LLM_TIMEOUT_SECONDS` | `120` | 请求超时时间（秒） |
### Browser
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `BROWSER_HEADLESS` | `false` | 以无头模式运行浏览器 |
| `BROWSER_USER_DATA_DIR` | `./browser_data` | 浏览器用户数据目录的路径 |
| `BROWSER_PROFILE_NAME` | `Default` | 要使用的浏览器配置文件名称 |
| `BROWSER_VIEWPORT_WIDTH` | `1920` | 默认视口宽度 (px) |
| `BROWSER_VIEWPORT_HEIGHT` | `1080` | 默认视口高度 (px) |
### Discovery
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DISCOVERY_MAX_DAILY` | `50` | 每天处理的最大机会数 |
| `DISCOVERY_SCHEDULE_INTERVAL_MINUTES` | `60` | 发现轮次之间的间隔（分钟） |
| `DISCOVERY_SEARCH_QUERIES` | `AI automation,AI readiness assessment,…` | 以逗号分隔的搜索查询 |
### Database
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_PATH` | `./data/leads.db` | SQLite 数据库文件路径 |
| `DATABASE_ECHO` | `false` | 记录所有 SQL 语句（调试） |
| `DATABASE_POOL_SIZE` | `5` | 连接池大小 |
| `DATABASE_POOL_OVERFLOW` | `10` | 最大溢出连接数 |
### HITL (Human-in-the-Loop)
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `HITL_ENABLED` | `true` | 启用 HITL 审查门禁 |
| `HITL_AUTO_APPROVE` | `false` | 在未经人工审查的情况下自动批准联系草稿 |
| `HITL_REVIEW_TIMEOUT_SECONDS` | `300` | 等待人工审查的最长秒数，超过则跳过 |
### Platforms
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PLATFORMS_ENABLED` | `upwork,linkedin,freelancer` | 以逗号分隔的已启用平台列表 |
### 平台凭证
这些仅通过环境变量设置（绝不硬编码）：
| 变量 | 描述 |
|----------|-------------|
| `UPWORK_USERNAME` | Upwork 账户邮箱/用户名 |
| `UPWORK_PASSWORD` | Upwork 账户密码 |
| `LINKEDIN_USERNAME` | LinkedIn 账户邮箱/用户名 |
| `LINKEDIN_PASSWORD` | LinkedIn 账户密码 |
| `FREELANCER_USERNAME` | Freelancer.com 账户用户名 |
| `FREELANCER_PASSWORD` | Freelancer.com 账户密码 |
## CLI 命令
| 命令 | 描述 |
|---------|-------------|
| `init` | 初始化数据库并创建 schema（幂等） |
| `discover` | 运行发现阶段 — 在已启用的平台上搜索新机会 |
| `pipeline` | 运行完整的 pipeline（发现 → 过滤 → 个性化 → 验证 → HITL） |
| `review` | 打开终端 UI，专注于审查队列以批准草稿 |
| `list` | 列出带有可选过滤器（状态、平台、限制）的机会 |
| `stats` | 显示聚合 pipeline 统计信息和平台细分数据 |
| `quickstart` | 交互式首次设置向导 — 在 2 分钟内配置 API key 和平台 |
| `serve` | 启动调度程序守护进程以进行定期发现运行 |
```
freelance-lead-gen --help
freelance-lead-gen init
freelance-lead-gen list --status qualified --limit 20
freelance-lead-gen stats
```
## 平台设置
### Upwork
1. 将您的凭证添加到 `.env` 中：`UPWORK_USERNAME` 和 `UPWORK_PASSWORD`
2. Upwork 提取器使用带身份验证的标准搜索界面
3. 反机器人配置：启用隐身、模拟人类鼠标移动、随机延迟
### LinkedIn
1. 将您的凭证添加到 `.env` 中：`LINKEDIN_USERNAME` 和 `LINKEDIN_PASSWORD`
2. LinkedIn 提取器使用基于关键字并带有分页的职位搜索
3. 反机器人配置：启用隐身、保守延迟、会话持久化
### Freelancer
1. 将您的凭证添加到 `.env` 中：`FREELANCER_USERNAME` 和 `FREELANCER_PASSWORD`
2. Freelancer 提取器使用公开的项目列表页面
3. 反机器人配置：具有更长随机延迟的增强型隐身
### 求职板（通用）
求职板使用带有基于 CSS 选择器配置的 `GenericPlaywrightExtractor`。公共板块无需身份验证。通过 `PLATFORMS_ENABLED` 变量进行配置。
### 添加新平台
请参阅[开发指南](docs/development.md#adding-a-new-platform)以获取有关创建自定义平台提取器的分步说明。
## 安全与 HITL (Human-in-the-Loop)
本系统将**安全和人工监督**作为核心理念进行设计：
- **代理绝不自主提交任何内容** — 它负责发现、筛选、起草和验证，但所有出站通信都需要通过审查队列获得明确的人工批准
- **HITL 审查门禁** — 每一份联系草稿在提交前都会呈现在终端 UI 中供人工审查
- **草稿版本控制** — 所有草稿的更改都会被追踪并保留完整的版本历史记录；您随时可以查看更改的内容
- **禁用短语检测** — 验证代理会在草稿进入审查阶段之前扫描有问题的语言模式
- **反 AI 内容门禁** — 可读性评分和 AI 标记检测有助于保持生成的内容自然，并避免被平台检测到
## 开发
```
# 安装 dev dependencies
uv sync --group dev
# 运行 tests
pytest
# 运行 coverage
pytest --cov=freelance_lead_gen --cov-report=term-missing
# Lint
ruff check src/
# Format
ruff format src/
# Type check
mypy src/
```
请参阅[开发指南](docs/development.md)了解详细的设置、测试规范和平台集成说明。
## 项目结构
```
freelance-lead-gen/
├── src/freelance_lead_gen/
│ ├── cli.py # Click CLI entry point
│ ├── llm.py # LLM client (OpenAI-compatible)
│ ├── agents/ # Pipeline agents
│ │ ├── orchestrator.py # LeadGenOrchestrator
│ │ ├── filtering_agent.py # Filtering & scoring
│ │ ├── personalization_agent.py # Outreach draft generation
│ │ ├── verification_agent.py # Quality & safety checks
│ │ └── profile_matcher.py # Skill/title similarity scoring
│ ├── config/ # Settings and prompt templates
│ │ ├── settings.py # Pydantic models for all config
│ │ └── prompts.py # LLM prompt templates
│ ├── discovery/ # Browser automation & extraction
│ │ ├── browser.py # ManagedBrowser (Playwright wrapper)
│ │ ├── discovery_agent.py # Coordination of extraction runs
│ │ ├── extractor.py # GenericPlaywrightExtractor
│ │ ├── scheduler.py # APScheduler periodic runner
│ │ └── platforms/ # Per-platform extractors
│ ├── models/ # Pydantic domain models
│ │ ├── opportunity.py
│ │ ├── pipeline.py
│ │ └── platform.py
│ ├── storage/ # Database layer
│ │ ├── database.py # SQLAlchemy async engine
│ │ ├── migrations.py # Inline migration runner
│ │ └── repository.py # OpportunityRepository
│ ├── ui/ # Textual terminal UI
│ │ ├── app.py # TUI application
│ │ ├── dashboard.py # Dashboard screen
│ │ ├── lead_list.py # Lead listing screen
│ │ ├── lead_detail.py # Lead detail screen
│ │ ├── content_editor.py # Draft editor screen
│ │ ├── review_queue.py # Review queue screen
│ │ └── widgets.py # Shared UI widgets
│ └── utils/ # Utilities
│ ├── fingerprint.py # Browser fingerprint generation
│ └── logging.py # Structured logging config
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── architecture.md
│ ├── development.md
│ └── security.md
└── .github/ # CI/CD, issue templates
```
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
*使用 Playwright、SQLAlchemy、Textual 和结构化的 LLM pipeline 构建。*
标签：DLL 劫持, Petitpotam, 商业爬虫, 大语言模型, 客户线索挖掘, 浏览器自动化, 特征检测, 终端用户界面, 请求拦截, 逆向工具