ai-freelance-copilot

AI Freelance 副驾驶 > 一个多智能体副驾驶，帮助您完成自由职业招募流程中的繁琐前期工作。它会搜索公开的机会源，评估每个潜在客户与您的技能匹配程度，研究潜在客户，并根据您的投资组合起草特定的、非垃圾的提案 — 量化成功案例贯穿始终。每个草稿都进入一个带有适配度一键链接的审核队列，您会收到摘要。决定发送什么。         ## 概述 **AI Freelance 副驾驶** 是一个多智能体系统，旨在为您完成自由职业招募流程中的繁琐前期工作。它会搜索公开的机会源，评估每个潜在客户与您的技能匹配程度，研究潜在客户，并根据您的投资组合起草特定的、非垃圾的提案 — 量化成功案例贯穿始终。每个草稿都进入一个带有适配度评分和一键链接的审核队列，您会收到摘要。由您决定发送什么。 该系统**默认离线运行**：确定性哈希嵌入器和内存向量存储意味着完整的测试套件和干燥运行不需要 API 密钥和网络。插入您的 Claude API 密钥，它会使用 Opus 起草；如果不插入，架构仍然可以端到端运行。 ## 它解决的问题 自由职业者在每天都会花费数小时在相同的重复工作中：浏览数十个列表，猜测哪些适合，研究客户，并撰写一份不像模板的新鲜提案。大多数人要么精疲力尽，要么开始发送通用副本 — 而平台会惩罚这种行为。 这个副驾驶将这种重复工作压缩成一个审核队列： - **发现** 跨多个只读源，无重复。 - **资格** 具有明确的 0-100 适配度评分和证明该评分的投资组合仓库。 - **研究 + 起草** 引用您实际的项目和通过 量化的结果。 - **合规门控草稿到达您之前拒绝任何太短、通用的内容。 - **硬成本上限** 以防止失控的运行悄悄花费您的 Claude 预算。 您花时间选择赢家并发送，而不是搜索工作板。 ## 工作原理和安全模型 该系统**从不自动向任何平台提交任何内容**。这是一个刻意的、承载负载的设计决策 — 而不是。 管道只会 → 资格 → 研究 → 起草 → 队列草稿写入本地状态为 `draft，并在审批仪表显示。**人类草稿并亲自到 Upwork / LinkedIn / 其他平台。 自动提交提案或连接请求**违反 Upwork、LinkedIn 和每个类似平台的服务条款**，并且是快速封禁账户的途径。因此： - 潜在客户来源是**只读**的 — 它们获取公共列表而非其他内容。 ` 和 `dry_run` 设置，以便人类驱动的仪表板可以将某个项目标记为**已被人类。没有代码路径会自由职业平台。 接近“提交”的 MCP 的 `mark 工具，它仅 CRM 中记录您。 ## 架构架构](docs/arch) 潜在客户来源馈一个获取和去，然后每个新潜在通过 **LangGraph智能体管道 — → 研究 → 编写 → 审核* — 器从投资组合** 知识库成本防护** 计量每个中提取证明批准的草稿中排队，**电子邮件/WhatsApp** 会发送出去审批仪表板** 审核和提交。当您标记一个潜在客户****时，**** 会将该提案嵌入回知识库`/metrics` 端点将所有内容公开给 Grafana。 >的图表源位于/architecture.drawio/architecture.drawio) [diagrams.net://app.diagrams 打开并修改。 智能体 |体 | 模型 | 角色 | |-------|-------|------| | **资格评估 | Sonnet（廉价） | 评估适配度 0 并将其映射到投资组合仓库。 | 研究员** | | 将机会总结化丰富信息（、痛点）。提案编写器 Opus（强大 通过 RAG 起身定制的提案，项目和量化结果| **合规审核员** |性规则）控：长度、邮件、必须引用重 — 在排队前批准或拒绝。 | | **跟进** |onnet |的潜在客户起短、有礼貌（仍由人类 | ## 潜在客户来源 所有来源都是读**的 —获取公共列表而。 | 来源 | 它读取的内容 | |--------|---------------| | **远程工作板** | RemoteOK、WeWorkRemotely 和 Remotive 源 — 开箱即用，无需配置。 | | **Contra / 初创公司** | 面向初创公司的机会源（可通过 `COPILUP_FEEDS）。 | | "谁在** | 每月的 招聘线程 Algolia API）。**带有公共联系邮箱的潜在客户主要来源** — 发布者经常发布“发送电子邮件至 jobs@company.com 申请”，这使得 [自动电子邮件外联](#自动电子邮件外联) 渠道成为可能。 | | **Upwork RSS** *(可选)* | Upwork **于 2024-08-20 停止公共 RSS**，因此默认情况下此功能已关闭。仅当您有第三方 RSS 桥时，请设置 `COPILOT_UPWORK_FEEDS`；否则，请使用 Upwork 的原生保存搜索警报并手动竞标。适配器在未配置时返回无（无错误）。 | > 大多数工作列表（Upwork、LinkedIn工作板）都链接回平台且**没有邮件**，因此它们仍需人类提交。 News “谁在招聘”评论是一个例外 — 也是唯一一个自动电子邮件渠道发送邮件的地方。 ## 自动电子邮件外联 提案管道**为人类起草和排队**，因为自动提交到 Upwork/LinkedIn 违反了他们的服务条款。但有一个渠道是**安全全自动的**：**从您自己的地址发送纯文本电子邮件** 给**公开发布联系地址** 寻找工作的人。这不是平台服务条款的违规行为，并且是邮件外联子系统（[`outreach/`](outreach/)）的基础。 它**默认关闭**，并且有意控制发送量。启用它，运行命令时添加 `--auto-email --notify`： ```bash python main.py run --auto-email --notify 每个**排队、适配度高** 的潜在客户，它会： 1. **提取联系邮箱** （[`outreach/extract.py`](outreach/extract.py)）从潜在客户描述/原始字段 — 拒绝 `noreply@`、 `@example.`/错误域实际上，这只会在谁在招聘”帖子上触发；工作列表地址为零，。 2. **起草一封简短（110–150 字）的人类冷介绍电子邮件** 使用 Opus （[`outreach/pitch.py`](outreach/pitch.py)）— 第一行特定于子，一个引用的项目，最多一个量化结果，一个软呼吁行动链接到预订链接，附上真实身份签名。 3. **通过您的 SMTP 发送**outreach/sender.py`](outreach/sender.py并记录一个 `OutreachRecord`。 开启所有防护措施：** - **主门控** — 除非 `COPILOT_AUTO_EMAIL=true` **和** `COPILOT_SMTP_HOST` 已设置，否则不会发送任何内容。否则发送者是一个硬 no-op，因此默认配置永远不会给任何人发送电子邮件。 - **适配度下限** — 只有评分 ≥ `COPILOT_OUTREACHIT` （默认 **80**）的潜在客户才会被联系。 - **每日上限** — 每天最多 `COPILOT_MAX_EMAILS_PER_DAY` （默认 **8**）封邮件。低发送量保护回复质量、域名声誉和合法性。 - **去重** — `outreach` 表有一个 **UNIQUE** 电子邮件列；一个地址 **永远不会被重复发送，跨运行。 - **抑制列表** — `data/suppressed.txt` （每行一个小写电子邮件）会在每次发送前被遵守。 将地址放入其中以永久停止发送邮件。 - **退出链接** — 每封邮件都带有纯文本身份 + 退出链接行（`Reply 'unsubscribe' …`）和 `Reply-To` 到 `COPILOT_OPT_OUT_MAILBOX`。 **合法性。** 这是 B2B 外联，针对**发布招聘联系信息**的人 — 一个教科书式的 **合法权益** 基础，符合英国 **PECR** / GDPR 和 CAN-SPAM：一个真实的发送者身份，一个真实的回复地址，一个简单的退出链接，没有欺骗，设计上低发送量。 它 **不是** 批量营销。Upwork/LinkedIn 提案仍需人类提交 — 此渠道 **仅限电子邮件**，从不触及平台 API。 > 运行统计数据包括 `emailed` 和 `emailed_skipped` 的详细情况（`no_email`, `low_fit`, `duplicate`, `suppressed`, `daily_cap`），您可以准确地看到每个潜在客户为什么被联系或未被联系。 ### 部署调度 外联运行无人值守，因此 **去重/上限状态运行之间持续** — 否则 `outreach` 表重置，您可能会重新给人们发送电子邮件。的方法： 1系统 cron 在一个的盒子上使用 **持久 SQLite （或 Kubernetes Cron数据库存储在，并在运行之间持续去重开箱。在计划命令 `--auto-email`环境变量。 2Hub Actions**`.github/workflows.yml`](.githubreach.yml)）— 运行器是 **的**，因此**将 `OT_DATABASE_URL指向 **持久托管。如果没有它，去重表将在每次被丢弃。工作日 00 UTC 运行调度除外），具有currency` 组，因此不会重叠，并从存储库机密中读取 `COPILOTROPIC_API_KEY` 、 `COPILOT_SMTP_*` 、 `COPILOT_AUTO_EMAIL` 和 `COPILOT_DATABASE_URL`。 ## 自动回复 当潜在客户回复其中一封冷邮件时，自动回复子系统（[`reply/`](reply/)）会通过 **IMAP** 读取回复并您的口吻回复** — 这样即使您在睡觉话也会继续。它 **完全自动协商** 回回答技术和问题），有一个硬，并且它只会与您实际发送邮件OutreachRecord现有的 `ReplyRecord`）交谈。 **硬防护措施** — 这里是安全措施： - **从不承诺价格、范围、时间表或合同。** 如果潜在客户询问费率、成本、预算、范围或截止日期，机器人会说这取决于具体细节，并**建议进行短暂的 [cal.com](cal.com/) 通话**，附带链接。它无法引用确定的数字、同意接受 NDA/合同。那些仍在您这边，在通话中。（如果您想让它提及大致范围，请设置 `COPILOT_STANDARD_RATE`；空白 = 。） 在每封邮件中都被抄送。** 每个自主消息都会复制到您的收件箱（`COPILOT_OPT_OUT_MAILBOX` 或您的所有者电子邮件），消息发送的那一刻就能看到发送了什么。 - **按线程限制。** 在给某个潜在客户发送 **COPILOT_MAX_REPLIES_PER_THREAD** （默认 **6**）封邮件后，机器人会停止回复该线程 — 硬性停止以防止回复循环。 - **取消订阅处理。** 不感兴趣/“取消订阅”/”/“停止”/恶意回复会被礼貌地确认，并将地址追加到抑制列表（`data/suppressed.txt`），以便不再发送任何内容。 - **诚实。** 它从不伪造超出您投资组合的经验。 在 [`.github/workflows/reply.yml`](.github/workflows/reply.yml) （每小时 2 次，周一至周五 08:00-18:）或运行 `python main.py reply`运行之前，通过设置 `COPILOT_AUTO_REPLY=true` 和您的 SMTP/IMAP 凭证（IMAP 重用 `COPILOT_SMTP_USER` + `COPILOT_SMTP_PASSWORDGmail 应用程序密码适用于两者）来启用它aude 存在实际未读回复时才会被调用，因此空收件箱运行不会产生任何成本 — 频繁轮询很便宜。与外联一样，每个线程的上限和对话日志都存储在数据库中短暂的运行，请将 `COPILOT_DATABASE_URL`持久的 Postgres。 > **仍需监控件箱。** 此运行**与**工作，而不是代替您。您在每封都被抄送，可以随时跳转到任何线程回复您自己，人工触摸接管。机器人故意将任何钱、范围或承诺的内容交给与 **您** 的通话。 ## 仪表板（任务控制中心） 系统所做的一切都在一个地方可见 — 并且镜像为 MCP 工具，以便智能体可以读取相同状态（用于未来自我改进）。  | 页面 | 显示内容 | |------|| **收件箱** |可编辑提案草稿和一键操作的前的潜在客户 | | **管道** |客户按状态已起草 → 已批准 → 已提交/已输） | | **外联** | 每封已发送的冷邮件 — 状态，已回复？，后续跟进 | | **对话** | 完整的回复线程（入站 + 代理的自动回复） | | **分析** | 渠道（已发送邮件 → 已回复 → 已赢），Claude 成本，当日邮件数量 | | **运行** | 每次运行 — ok/成本，关键统计数据（失败时会通过电子邮件通知您）它：`python main.py dashboard` → `http://localhost:8000`。 相同的数据通过 MCP 给智能体：`funnel_stats`list_outreach`list_con，`run。 **仪表板身份验证。** UI写入操作都受到 **HTTP 基本身份验证保护（恒定时间凭证检查）。在公共 URL 上公开之前，请COPILOT_D_USER` （默认 `admin`）COPILOT_D_PASSWORD`**。**空白** `COPILASHBOARD_PASSWORD禁用身份验证（在本地/SSH 中很方便healthz`metrics` 和 HMAC 验证的 `POSThooks/cal` ，以便健康检查etheus 抓取和 cal.com 继续工作在 Render 上 HTTPS 的信息 [`DEPLOY.mdLOY.md)。 **呼叫跟踪。** 要完成渠道（已 → 已回复 → **已预订呼叫** → 已赢添加一个 [](https://cal.com) 的 `BOOK 事件的子，指向 `https://<your-dashboard-host>/webhooks/cal`，并在 `COPILOT_CAL_WEBHOOK_SECRET` 中设置共享密钥（端点验证 `X-Cal-Signature-256`；留空可在开发环境中跳过验证）。当您发送邮件的某人预订呼叫时，该外联行将被标记为 `call_booked_at`，并且分析中的“已预订呼叫”栏会亮起。仪表板必须 **公开可才能触发网络钩子 — 本地它。 成本防护 运行都会创建一个 `CostTracker`，并以 `COPILOT_MAX_USD_PER_RUN` （默认 **$2.00**）进行种子化。计量 LLM 包装器会在每次 Claude 调用**检查预算，并在调用**之后**牌使用情况。当累计支出达到，下一个调用会引发 `Budgeted`，运行干净地停止标记为 `budget_exhausted` — 不会崩溃，不意外账单。定价按模型跟踪（Opus 4.8 美元/25 MTok，$25 美元ok）。 ## 可观察性板公开了一个 Prometheus `/metrics`。关键指标： - `_leads_fetched_total`，ilot_leads_qualified_total`copilot_proposals_drafted `copilot_proposals_w`，`copilot_proposals_total` - `copilot_cl_usd_total` - `cop_score`，`copilot_pro`，`copilot_ragieval_seconds` （直方图） 一个现成的 Grafana 仪表[`monitoring/grafana-dashboardmonitoring/grafana-dashboard.json)）位于此处 — 在 Kubernetes 中，[`/servicemonitor.yaml`](s/servicemonitor.yaml) Operator 连接到刮取 `/metrics## 学习循环 当您在上标记一个潜在客户****时，`record_outcome` 将其状态翻转为已获胜，标记提案，并**将获胜提案嵌入回 RAG 知识库**，作为一个 `kind: "win"` 文档。因为提案编写器从同一个存储中检索证明点，所以未来的草稿开始引用实际成交的案例 — 系统逐渐积累了自己的胜利。标记潜在客户**输掉** 记录结果而不会触及知识库。 ## 入站内容引擎 除了外外，一个小型内容引擎从同一投资组合知识库起草**入站 — LinkedIn帖子、案例研究和工作描述 — 因此赢的渠道也有助于吸引客户： ```bash python main.py content case-study --topic "Kubernetes 成本优化" ``` ## 仓库结构 ```text ai-freelance-copilot/ ├── main.py # 命令行入口（运行 / 仪表盘 / MCP / 构建知识库 / 统计 / 内容） ├── pipeline.py # 集成核心：获取 → 图谱 → 队列（从不提交） ├── config.py # pydantic 设置（安全，离线默认值） ├── costs.py # 成本跟踪器 + 每次运行的预算限制 ├── core/ │ ├── schemas.py # 共享 Pydantic 契约（Lead，ScoredLead，...） │ └── state.py # LangGraph CopilotState ├── agents/ │ ├── graph.py # LangGraph 调度器（资格 → 研究 → 撰写 → 审查） │ ├── llm.py # 计量 Claude 包装器 + 离线 FakeChat │ ├── qualifier.py # 适合度评分（Sonnet） │ ├── researcher.py # 丰富（Sonnet） │ ├── proposal_writer.py # 基于 RAG 的草稿（Opus） │ ├── compliance.py # 确定性审查门控 │ └── followup.py # 礼貌的提醒草稿 ├── sources/ # 只读线索适配器 + 注册表 ├── outreach/ # 自动电子邮件通道：提取 → 推介 → 发送（门控，重复数据删除，退出） ├── reply/ # 自动回复：收件箱（IMAP）→ 响应（受限）→ 发送者 → 运行者 ├── rag/ # 嵌入器，矢量存储，检索器，摄取，学习循环 ├── db/ # SQLAlchemy 模型 + 会话 ├── observability/metrics.py # Prometheus 指标（如果不存在则为空） ├── interfaces/ │ ├── dashboard.py # FastAPI 审批仪表盘 + /metrics + /healthz │ ├── notify.py # 电子邮件 / WhatsApp 摘要 │ └── mcp_server.py # FastMCP 标准输入/输出服务器，用于 AI 客户端 ├── content/ # 入站内容引擎（帖子 / 案例研究 / 任务） ├── scripts/build_kb.py # 构建投资组合 RAG 知识库 ├── monitoring/grafana-dashboard.json ├── k8s/ # 部署，cronjob，服务，configmap，密钥，服务监视器 ├── docs/architecture.drawio ├── tests/ # 离线测试套件（无 API 密钥，无网络） ├── Dockerfile · Makefile · requirements.txt · pyproject.toml └── .github/workflows/ # ci.yml · outreach.yml（定时自动电子邮件）· reply.yml（定时自动回复） ``` ## 前置条件 - **Python 3.11+** - **Anthropic（Claude）API 密钥** - 可选：系统运行且测试完全离线，无需 API 密钥（确定性嵌入器 + `FakeChat`）。仅在实时草稿时需要密钥。 - （可选）用于电子邮件摘要的 SMTP 凭证，或 WhatsApp Business Cloud API 令牌。 - （可选）用于部署的 Docker + Kubernetes 集群。 ## 快速入门 ```bash # 1. 克隆并进入仓库 git clone https://github.com/suryaanandan1995-dotcom/ai-freelance-copilot.git cd ai-freelance-copilot # 2. 创建虚拟环境并安装 python3.11 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. 构建投资组合知识库（离线，无 API 密钥） python -m scripts.build_kb # 4. 运行一次流水线（发现 → 资格 → 研究 → 草稿 → 队列） python main.py run # 5. 启动审批仪表盘，然后打开 http://localhost:8000 python main.py dashboard ``` 要接收摘要，请复制 `.env.example` 到 `.env` 并配置 SMTP（`COPILOT_SMTP_HOST`、`COPILOT_SMTP_USER` 等）或 WhatsApp 变量，并设置 `COPILOT_NOTIFY_CHANNEL`。在 `python main.py run` 后添加 `--notify` 以发送一个。 ## 配置 所有变量均以 `COPILOT_` 为前缀（参见 [`.env.example`](.env.example)）。 | 变量 | 默认值 | 描述 | | --- | --- | --- | | `COPILOT_DATABASE_URL` | `sqlite:///copilot.db` | 存储 DSN（生产环境中使用 PostgreSQL）。 | | `ANTHROPIC_API_KEY` | _空_ | Claude API 密钥（仅实时运行）。 | | `COPILOT_MODEL_OPUS` | `claude-opus-4-8` | 用于草稿的强模型。 | | `COPILOT_MODEL_SONNET` | `claude-sonnet-4-6` | 用于评分/分类的廉价模型。 | | `COPILOT_MAX_USD_PER_RUN` | `2.0` | 每次运行的硬性 Claude 支出上限。 | | `COPILOT_MIN_FIT_SCORE` | `70` | 低于此分数的线索将被丢弃。 | | `COPILOT_MAX_LEADS_PER_RUN` | `50` | 每次运行处理的最大线索数量。 | | `COPILOT_MAX_PROPOSALS_PER_DAY` | `15` | 反垃圾邮件每日草稿上限。 | | `COPILOT_DRY_RUN` / `COPILOT_ALLOW_SEND` | `true` / `false` | 安全标志 — 永远不会启用自动发送。 | | `COPILOT_NOTIFY_CHANNEL` | `email` | `email` · `whatsapp` · `none`。 | | `COPILOT_DASHBOARD_BASE_URL` | `http://localhost:8000` | 用于摘要中的链接的基础 URL。 | | `COPILOT_SMTP_HOST` … `COPILOT_NOTIFY_EMAIL_TO` | _空_ | SMTP 摘要配置。 | | `COPILOT_WHATSAPP_TOKEN` / `_PHONE_ID` / `_TO` | _空_ | WhatsApp Business Cloud API。 | | `COPILOT_RAG_STORE_PATH` | `data/portfolio_kb.json` | 矢量存储路径。 | | `COPILOT_OWNER_*` | Surya A | 用于提案/签名的身份。 | ## 部署 **Docker** ```bash docker build -t ghcr.io/suryaanandan1995-dotcom/ai-freelance-copilot:latest . docker run --rm -p 8000:8000 --env-file .env \ ghcr.io/suryaanandan1995-dotcom/ai-freelance-copilot:latest ``` 镜像以非 root 用户身份运行，默认提供仪表盘。 **Kubernetes** ([`k8s/`](k8s/)) ```bash kubectl apply -f k8s/configmap.yaml cp k8s/secret.example.yaml k8s/secret.yaml # 填写真实值，不要提交 kubectl apply -f k8s/secret.yaml kubectl apply -f k8s/deployment.yaml -f k8s/service.yaml kubectl apply -f k8s/cronjob.yaml # 周一至周五 `python main.py run --notify` kubectl apply -f k8s/servicemonitor.yaml # Prometheus 抓取 /metrics ``` **部署** 提供始终在线的审批仪表盘；**CronJob** 运行工作日（周一至周五）的发现传递并发送摘要。两者都以只读 rootfs、非 root 用户运行，并丢弃所有功能。 **定时自动电子邮件外联。** 要在定时运行 [自动电子邮件通道](#自动电子邮件外联)，请在重复命令中添加 `--auto-email`（`python main.py run --auto-email --notify`）并设置 `COPILOT_AUTO_EMAIL=true` + SMTP 凭证。因为重复数据删除/上限状态必须在运行中持续存在，请使用 **持久 SQLite 文件**（cron/Kubernetes CronJob 在始终在线的机器上）或 **持久托管 Postgres `COPILOT_DATABASE_URL`**（GitHub Actions [`outreach.yml`](.github/workflows/outreach.yml)，因为其运行器是短暂的）。 ## CI/CD GitHub Actions 在每次推送和拉取请求到 `main` 时运行（[`.github/workflows/ci.yml`](.github/workflows/ci.yml)）： 1. 检出 (`actions/checkout@v4`) 2. 设置 Python 3.11 (`actions/setup-python@v5`) 3. `pip install -r requirements.txt` 4. `ruff check .` 5. `pytest -q` 工作流声明 `permissions: contents: read`（最小特权）。完整的测试套件是确定性的，**离线运行** — 无 API 密钥，无网络。 ## 许可证 在 [MIT License](LICENSE) 下发布。 ## 作者 **Surya A** — DevSecOps + AI 基础设施工程师 - 电子邮件：suryaanandan1995@gmail.com - LinkedIn：https://www.linkedin.com/in/surya-devsecops/