github-reachout 0.1.0__py3-none-any.whl

github_reachout/nodes.py

@@ -0,0 +1,386 @@
+"""
+LangGraph 节点函数模块。
+
+节点列表：
+  1. plan       — 规划本轮执行步骤
+  2. fetch      — 获取 GitHub 用户信息和仓库
+  3. enrich     — 读取 LinkedIn/个人主页等网页内容
+  4. summarize  — LLM 总结技术方向
+  5. generate   — LLM 生成触达邮件
+  6. validate   — 校验邮件可发送性 + 技术方向匹配
+  7. send       — 发送邮件
+  8. evaluate   — 评估是否继续循环
+"""
+from __future__ import annotations
+
+import json
+from typing import Dict, Any
+
+from github_reachout.llm import LLMClient
+from github_reachout.github_client import GitHubClient
+from github_reachout.web_reader import WebReader
+from github_reachout.email_client import EmailClient
+from github_reachout.state import ReachoutState
+
+STEP_ORDER = ["plan", "fetch", "enrich", "summarize", "generate", "validate", "send", "evaluate"]
+ALL_STEPS = ["fetch", "enrich", "summarize", "generate", "validate", "send", "evaluate"]
+VALID_STEPS = set(ALL_STEPS)
+
+
+# ── 公共辅助 ──
+
+def _state_get(state: dict, *keys_with_defaults):
+    """批量从 state 取值，返回 tuple。用法: persons, errors = _state_get(state, ('persons', []), ('errors', []))"""
+    return tuple(state.get(k, d) for k, d in keys_with_defaults)
+
+
+# ── 1. plan ──
+
+def plan_node(state: ReachoutState, llm: LLMClient) -> Dict[str, Any]:
+    """规划本轮执行步骤。第 1 轮全量，后续 LLM 规划。"""
+    loop_count = state.get("loop_count", 0)
+
+    try:
+        if loop_count == 0:
+            planned = list(ALL_STEPS)
+        else:
+            persons = state.get("persons", [])
+            errors = state.get("errors", [])
+            system = (
+                "你是一个流程规划专家。根据当前状态，决定下一轮需要执行哪些步骤。\n"
+                "可选步骤：fetch, enrich, summarize, generate, validate, send, evaluate\n"
+                "规则：\n"
+                "- evaluate 必须始终包含\n"
+                "- 如果有人未获取 GitHub 信息，需要 fetch\n"
+                "- 如果有人未读取网页内容，需要 enrich\n"
+                "- 如果有人未总结技术方向，需要 summarize\n"
+                "- 如果有人未生成邮件，需要 generate\n"
+                "- 如果有人未校验邮件，需要 validate\n"
+                "- 如果有邮件校验通过但未发送，需要 send\n"
+                "- 步骤必须按顺序执行\n"
+                "返回 JSON：{\"planned_steps\": [\"step1\", \"step2\", ...]}"
+            )
+            user_msg = f"循环次数: {loop_count}\n已处理人数: {len(persons)}\n错误数: {len(errors)}\n人员状态:\n"
+            for p in persons:
+                user_msg += f"  - {p.get('login', '?')}: tech={'Y' if p.get('tech_direction') else 'N'}, ready={'Y' if p.get('email_ready') else 'N'}, sent={'Y' if p.get('email_sent') else 'N'}\n"
+
+            result = llm.chat_json(system, user_msg, temperature=0.1)
+            planned = [s for s in result.get("planned_steps", []) if s in VALID_STEPS]
+            if "evaluate" not in planned:
+                planned.append("evaluate")
+
+        return {"planned_steps": planned, "loop_count": loop_count}
+
+    except Exception as e:
+        print(f"  [plan] 规划失败，回退全量执行: {e}")
+        return {"planned_steps": list(ALL_STEPS), "loop_count": loop_count}
+
+
+# ── 2. fetch ──
+
+def fetch_node(state: ReachoutState, github: GitHubClient) -> Dict[str, Any]:
+    """获取 GitHub 用户信息和仓库列表。增量处理：跳过已处理的 login。"""
+    login_ids, processed, existing_persons, errors = _state_get(
+        state, ("login_ids", []), ("processed_logins", []), ("persons", []), ("errors", []))
+
+    new_persons, new_processed, new_errors = [], list(processed), list(errors)
+
+    for login in login_ids:
+        if login in processed:
+            continue
+        try:
+            print(f"  [fetch] 获取 {login} 的 GitHub 信息...")
+            new_persons.append(github.fetch_person(login))
+            new_processed.append(login)
+        except Exception as e:
+            print(f"  [fetch] 获取 {login} 失败: {e}")
+            new_errors.append({"step": "fetch", "login": login, "error": str(e)})
+            new_processed.append(login)
+
+    return {"persons": existing_persons + new_persons, "processed_logins": new_processed, "errors": new_errors}
+
+
+# ── 3. enrich ──
+
+def enrich_node(state: ReachoutState, web_reader: WebReader) -> Dict[str, Any]:
+    """读取 LinkedIn/个人主页等网页内容。"""
+    persons, errors = _state_get(state, ("persons", []), ("errors", []))
+
+    for p in persons:
+        if p.get("web_summary"):
+            continue
+        linkedin_url, blog_url, github_url = p.get("linkedin_url", ""), p.get("blog", ""), p.get("html_url", "")
+        if not linkedin_url and not blog_url and not github_url:
+            continue
+        try:
+            print(f"  [enrich] 读取 {p.get('login', '?')} 的网页内容...")
+            web_text = web_reader.read_person_pages(linkedin_url=linkedin_url, github_url=github_url, blog_url=blog_url)
+            if web_text:
+                p["web_summary"] = web_text
+        except Exception as e:
+            print(f"  [enrich] 读取 {p.get('login', '?')} 网页失败: {e}")
+            errors.append({"step": "enrich", "login": p.get("login", "?"), "error": str(e)})
+
+    return {"persons": persons, "errors": errors}
+
+
+# ── 4. summarize ──
+
+def summarize_node(state: ReachoutState, llm: LLMClient) -> Dict[str, Any]:
+    """LLM 总结每个人的技术方向。"""
+    persons, errors = _state_get(state, ("persons", []), ("errors", []))
+
+    for p in persons:
+        if p.get("tech_direction"):
+            continue
+        try:
+            print(f"  [summarize] 总结 {p.get('login', '?')} 的技术方向...")
+            context_parts = []
+            for key, label in [("bio", "Bio"), ("company", "Company"), ("location", "Location")]:
+                if p.get(key):
+                    context_parts.append(f"{label}: {p[key]}")
+
+            repos = p.get("repos", [])
+            if repos:
+                repo_desc = "\n".join(
+                    f"  - {r.get('name', '?')} ({r.get('language', '?')}, stars={r.get('stargazers_count', 0)}): {r.get('description', '')}"
+                    for r in repos[:10])
+                context_parts.append(f"Top Repos:\n{repo_desc}")
+
+            web_summary = p.get("web_summary", "")
+            if web_summary:
+                context_parts.append(f"Web Content:\n{web_summary[:2000]}")
+
+            if not context_parts:
+                p["tech_direction"] = "unknown"
+                continue
+
+            system = (
+                "你是一个技术方向分析专家。根据 GitHub 用户的仓库、bio、网页内容等信息，总结该用户的核心技术方向。\n"
+                "要求：\n- 用 3-5 个关键词描述技术方向\n- 识别主要编程语言和技术栈\n- 判断技术深度和领域专长\n"
+                "返回 JSON：{\"tech_direction\": \"关键词1, 关键词2, 关键词3\", \"primary_language\": \"xxx\", \"seniority\": \"junior/mid/senior/staff\"}"
+            )
+            result = llm.chat_json(system, f"GitHub 用户: {p.get('login', '?')}\n\n" + "\n\n".join(context_parts), temperature=0.1)
+            p["tech_direction"] = result.get("tech_direction", "unknown")
+            p["primary_language"] = result.get("primary_language", "")
+            p["seniority"] = result.get("seniority", "")
+        except Exception as e:
+            print(f"  [summarize] 总结 {p.get('login', '?')} 失败: {e}")
+            p["tech_direction"] = p.get("tech_direction") or "unknown"
+            errors.append({"step": "summarize", "login": p.get("login", "?"), "error": str(e)})
+
+    return {"persons": persons, "errors": errors}
+
+
+# ── 5. generate ──
+
+def generate_node(state: ReachoutState, llm: LLMClient) -> Dict[str, Any]:
+    """LLM 为每个人生成触达邮件。"""
+    persons, errors = _state_get(state, ("persons", []), ("errors", []))
+    target_tech = state.get("target_tech_direction", "")
+    company_name = state.get("company_name", "")
+    sender_name = state.get("sender_name", "")
+    sender_title = state.get("sender_title", "")
+
+    for p in persons:
+        if p.get("reachout_email"):
+            continue
+        try:
+            print(f"  [generate] 生成 {p.get('login', '?')} 的触达邮件...")
+            context_parts = []
+            if p.get("name"):
+                context_parts.append(f"Name: {p['name']}")
+            context_parts.append(f"GitHub: {p.get('login', '?')}")
+            for key, label in [("tech_direction", "Tech Direction"), ("bio", "Bio"), ("company", "Current Company")]:
+                if p.get(key):
+                    context_parts.append(f"{label}: {p[key]}")
+
+            repos = p.get("repos", [])
+            if repos:
+                repo_list = ", ".join(f"{r.get('name', '?')}({r.get('language', '?')})" for r in repos[:5])
+                context_parts.append(f"Notable Projects: {repo_list}")
+
+            system = (
+                "你是一个专业的技术招聘邮件撰写专家。根据候选人的技术背景，生成一封个性化的触达邮件。\n"
+                "要求：\n- 邮件必须完全写好，不能包含任何占位符\n- 用候选人的真实姓名或 GitHub ID 称呼\n"
+                "- 提及候选人的具体项目或技术方向\n- 语气专业但友好\n- 邮件长度 150-300 字\n"
+                "返回 JSON：{\"subject\": \"邮件主题\", \"body\": \"邮件正文\"}"
+            )
+            user_msg = (
+                f"候选人信息:\n" + "\n".join(context_parts) + "\n\n"
+                f"我方信息:\n- 公司: {company_name}\n- 联系人: {sender_name} ({sender_title})\n- 目标技术方向: {target_tech}\n"
+            )
+            result = llm.chat_json(system, user_msg, temperature=0.5)
+            p["reachout_email"] = json.dumps(result, ensure_ascii=False)
+            p["email_subject"] = result.get("subject", "")
+            p["email_body"] = result.get("body", "")
+        except Exception as e:
+            print(f"  [generate] 生成 {p.get('login', '?')} 邮件失败: {e}")
+            errors.append({"step": "generate", "login": p.get("login", "?"), "error": str(e)})
+
+    return {"persons": persons, "errors": errors}
+
+
+# ── 6. validate ──
+
+def validate_node(state: ReachoutState, llm: LLMClient) -> Dict[str, Any]:
+    """校验邮件是否可直接发送：无占位符 + 技术方向匹配 + 有邮箱。"""
+    persons, errors = _state_get(state, ("persons", []), ("errors", []))
+    target_tech = state.get("target_tech_direction", "")
+    emails_to_send = []
+
+    for p in persons:
+        login = p.get("login", "?")
+        if p.get("email_ready"):
+            emails_to_send.append(p)
+            continue
+
+        email_body, email_subject = p.get("email_body", ""), p.get("email_subject", "")
+        if not email_body:
+            continue
+
+        # 占位符检查
+        validation = EmailClient.validate_email_ready(email_body, email_subject)
+        if not validation["ready"]:
+            print(f"  [validate] {login} 邮件校验不通过: {validation['issues']}")
+            p["email_ready"] = False
+            errors.append({"step": "validate", "login": login, "error": f"邮件校验失败: {validation['issues']}"})
+            continue
+
+        # 技术方向匹配
+        if target_tech:
+            try:
+                if not _check_tech_match(llm, p.get("tech_direction", ""), target_tech):
+                    print(f"  [validate] {login} 技术方向不匹配")
+                    p["email_ready"] = False
+                    p["tech_mismatch"] = True
+                    continue
+            except Exception:
+                pass  # 降级：匹配失败时仍允许发送
+
+        # 收件人邮箱
+        if not p.get("email"):
+            print(f"  [validate] {login} 无公开邮箱")
+            p["email_ready"] = False
+            p["no_email"] = True
+            continue
+
+        p["email_ready"] = True
+        emails_to_send.append(p)
+        print(f"  [validate] {login} 邮件校验通过")
+
+    return {"persons": persons, "emails_to_send": emails_to_send, "errors": errors}
+
+
+def _check_tech_match(llm: LLMClient, tech_direction: str, target_tech: str) -> bool:
+    """用 LLM 判断技术方向是否匹配。"""
+    result = llm.chat_json(
+        "判断候选人的技术方向是否与目标方向匹配。匹配标准：有至少一个核心技术领域重叠即可。\n"
+        "返回 JSON：{\"match\": true/false, \"reason\": \"简短说明\"}",
+        f"候选人技术方向: {tech_direction}\n目标技术方向: {target_tech}",
+        temperature=0.0,
+    )
+    return bool(result.get("match", False))
+
+
+# ── 7. send ──
+
+def send_node(state: ReachoutState, email_client: EmailClient) -> Dict[str, Any]:
+    """发送校验通过的触达邮件。"""
+    persons, sent_results, errors = _state_get(
+        state, ("persons", []), ("sent_results", []), ("errors", []))
+    new_sent = list(sent_results)
+
+    for p in persons:
+        login = p.get("login", "?")
+        if p.get("email_sent") or not p.get("email_ready"):
+            continue
+        to_email = p.get("email", "")
+        if not to_email:
+            continue
+
+        try:
+            print(f"  [send] 发送邮件给 {login} ({to_email})...")
+            result = email_client.send_email(to=to_email, subject=p.get("email_subject", ""), body=p.get("email_body", ""))
+            p["email_sent"] = result["success"]
+            p["email_sent_error"] = "" if result["success"] else result["error"]
+            new_sent.append({"login": login, "success": result["success"], "error": result.get("error", "")})
+            if not result["success"]:
+                errors.append({"step": "send", "login": login, "error": result["error"]})
+            print(f"  [send] {'OK' if result['success'] else 'FAIL'} {login}")
+        except Exception as e:
+            p["email_sent"] = False
+            p["email_sent_error"] = str(e)
+            new_sent.append({"login": login, "success": False, "error": str(e)})
+            errors.append({"step": "send", "login": login, "error": str(e)})
+
+    return {"persons": persons, "sent_results": new_sent, "errors": errors}
+
+
+# ── 8. evaluate ──
+
+def evaluate_node(state: ReachoutState, llm: LLMClient) -> Dict[str, Any]:
+    """评估是否继续循环。"""
+    persons = state.get("persons", [])
+    login_ids = state.get("login_ids", [])
+    loop_count = state.get("loop_count", 0)
+    max_loops = state.get("max_loops", 3)
+    errors = state.get("errors", [])
+    loop_history = state.get("loop_history", [])
+
+    # 统计
+    email_sent = sum(1 for p in persons if p.get("email_sent"))
+    no_email = sum(1 for p in persons if p.get("no_email"))
+    tech_mismatch = sum(1 for p in persons if p.get("tech_mismatch"))
+
+    loop_history.append({
+        "loop": loop_count,
+        "total": len(login_ids),
+        "processed": len(persons),
+        "email_sent": email_sent,
+        "no_email": no_email,
+        "tech_mismatch": tech_mismatch,
+        "errors_count": len(errors),
+    })
+
+    # 硬性判断
+    all_done = len(persons) >= len(login_ids)
+    all_resolved = (email_sent + no_email + tech_mismatch) >= len(persons)
+
+    if (all_done and all_resolved) or loop_count >= max_loops - 1:
+        print(f"  [evaluate] 结束循环 (已处理: {len(persons)}, 已发送: {email_sent})")
+        return {"continue_loop": False, "loop_count": loop_count + 1, "loop_history": loop_history}
+
+    print(f"  [evaluate] 继续循环 (已处理: {len(persons)}/{len(login_ids)}, 已发送: {email_sent})")
+    return {"continue_loop": True, "loop_count": loop_count + 1, "loop_history": loop_history}
+
+
+# ── 条件路由 ──
+
+def route_after_plan(state: ReachoutState) -> str:
+    """plan 后路由：按 STEP_ORDER 找第一个 planned 步骤。"""
+    planned = state.get("planned_steps", [])
+    for step in STEP_ORDER:
+        if step != "plan" and step in planned:
+            return step
+    return "evaluate"
+
+
+def route_after_step(current_step: str):
+    """步骤后路由：找 planned_steps 中当前步骤之后的第一个步骤。"""
+    def router(state: ReachoutState) -> str:
+        planned = state.get("planned_steps", [])
+        found = False
+        for step in STEP_ORDER:
+            if step == current_step:
+                found = True
+                continue
+            if found and step in planned:
+                return step
+        return "evaluate"
+    return router
+
+
+def route_after_evaluate(state: ReachoutState) -> str:
+    """evaluate 后路由：继续循环或结束。"""
+    return "plan" if state.get("continue_loop", False) else "__end__"

github_reachout/state.py

@@ -0,0 +1,70 @@
+"""
+Github-reachout 状态定义模块。
+
+定义 LangGraph 图中流转的 State 结构，
+遵循设计哲学：状态驱动、单向流动、逐步丰富。
+"""
+from __future__ import annotations
+
+from typing import TypedDict, Optional, List, Dict, Any
+
+
+class PersonInfo(TypedDict, total=False):
+    """单个 GitHub 用户的完整信息。"""
+    login: str                       # GitHub login id
+    name: str                        # 显示名称
+    bio: str                         # GitHub bio
+    location: str                    # 所在地
+    company: str                     # 公司
+    blog: str                        # 个人网站/博客
+    linkedin_url: str                # LinkedIn 主页链接（从 bio/blog 等提取）
+    public_repos: int                # 公开仓库数
+    followers: int                   # 粉丝数
+    avatar_url: str                  # 头像 URL
+    html_url: str                    # GitHub 主页 URL
+    repos: List[Dict[str, Any]]      # 仓库列表 [{name, description, language, stars, url}]
+    web_summary: str                 # 网页阅读总结（LinkedIn/个人主页等）
+    tech_direction: str              # LLM 总结的技术方向
+    email: str                       # 联系邮箱（从 GitHub profile 或网页获取）
+    reachout_email: str              # 生成的触达邮件内容
+    email_ready: bool                # 邮件是否可直接发送（无占位符、技术方向匹配）
+    email_sent: bool                 # 邮件是否已发送
+    email_sent_error: str            # 发送失败时的错误信息
+
+
+class ReachoutState(TypedDict, total=False):
+    """
+    Github-reachout 主状态。
+
+    数据流：login_ids → fetch → enrich → summarize → generate_email → validate → send
+    每个节点只关心自己需要的字段，返回自己负责的字段。
+    """
+    # ── 输入 ──
+    login_ids: List[str]             # 输入的 GitHub login id 列表
+    target_tech_direction: str       # 目标技术方向（用于匹配和邮件生成）
+    company_name: str                # 我方公司名称
+    sender_name: str                 # 发件人姓名
+    sender_title: str                # 发件人职位
+    sender_email: str                # 发件人邮箱（从 .env 读取）
+
+    # ── 规划 ──
+    planned_steps: List[str]         # 本轮计划执行的步骤
+    loop_count: int                  # 当前循环次数
+    max_loops: int                   # 最大循环次数
+    continue_loop: bool              # 是否继续循环
+
+    # ── 执行结果 ──
+    persons: List[PersonInfo]        # 所有人员信息（逐步丰富）
+    processed_logins: List[str]      # 已处理的 login id（增量去重）
+
+    # ── 邮件 ──
+    emails_to_send: List[Dict[str, Any]]  # 待发送邮件列表 [{to, subject, body}]
+    sent_results: List[Dict[str, Any]]    # 发送结果 [{login, success, error}]
+
+    # ── 循环控制 ──
+    loop_history: List[Dict[str, Any]]    # 每轮循环摘要
+    errors: List[Dict[str, Any]]          # 错误记录 [{step, login, error}]
+
+    # ── 断点续跑 ──
+    run_id: str                      # 运行 ID
+    step_index: int                  # 当前步骤序号

github_reachout/web_reader.py

@@ -0,0 +1,102 @@
+"""
+网页阅读器模块。
+
+功能：
+  - 读取 LinkedIn/GitHub/个人博客等网页内容
+  - 提取纯文本（去除 HTML 标签）
+  - 速率控制
+"""
+from __future__ import annotations
+
+import re
+import time
+
+import requests
+
+
+class WebReader:
+    """轻量级网页阅读器。"""
+
+    def __init__(self, timeout: int = 30, max_length: int = 8000, delay: float = 1.0):
+        self.timeout = timeout
+        self.max_length = max_length
+        self.delay = delay
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/120.0.0.0 Safari/537.36"
+            ),
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8",
+        })
+        self._last_request_time = 0.0
+
+    def fetch_page(self, url: str) -> str:
+        """获取网页内容并提取纯文本。"""
+        elapsed = time.time() - self._last_request_time
+        if elapsed < self.delay:
+            time.sleep(self.delay - elapsed)
+
+        try:
+            resp = self.session.get(url, timeout=self.timeout, allow_redirects=True)
+            resp.raise_for_status()
+            self._last_request_time = time.time()
+
+            content_type = resp.headers.get("Content-Type", "")
+            if "text/html" not in content_type and "text/plain" not in content_type:
+                return ""
+
+            text = self._html_to_text(resp.text)
+            if len(text) > self.max_length:
+                text = text[:self.max_length] + "\n...[truncated]"
+            return text
+
+        except requests.RequestException as e:
+            print(f"  [WebReader] 获取网页失败 {url}: {e}")
+            return ""
+
+    def read_person_pages(
+        self,
+        linkedin_url: str = "",
+        github_url: str = "",
+        blog_url: str = "",
+    ) -> str:
+        """读取一个人的所有相关网页，合并为一段文本。"""
+        sources = [
+            ("LinkedIn", linkedin_url),
+            ("Personal Blog", blog_url),
+            ("GitHub Profile", github_url),
+        ]
+        parts = []
+        for label, url in sources:
+            if not url:
+                continue
+            # blog_url 可能没有协议前缀
+            if not url.startswith(("http://", "https://")):
+                url = f"https://{url}"
+            text = self.fetch_page(url)
+            if text:
+                parts.append(f"=== {label} ===\n{text}")
+        return "\n\n".join(parts)
+
+    @staticmethod
+    def _html_to_text(html: str) -> str:
+        """将 HTML 转换为纯文本（不依赖 BeautifulSoup）。"""
+        # 移除 script/style
+        text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.DOTALL | re.IGNORECASE)
+        text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.DOTALL | re.IGNORECASE)
+        # 块级标签换行
+        text = re.sub(r'<br\s*/?\s*>', '\n', text, flags=re.IGNORECASE)
+        text = re.sub(r'</?(p|div|h[1-6]|li|tr|section|article)[^>]*>', '\n', text, flags=re.IGNORECASE)
+        # 移除标签
+        text = re.sub(r'<[^>]+>', '', text)
+        # HTML 实体
+        for entity, char in [("&amp;", "&"), ("&lt;", "<"), ("&gt;", ">"),
+                             ("&quot;", '"'), ("&#39;", "'"), ("&nbsp;", " ")]:
+            text = text.replace(entity, char)
+        # 压缩空白
+        text = re.sub(r'[ \t]+', ' ', text)
+        text = re.sub(r'\n\s*\n', '\n\n', text)
+        return text.strip()