github-reachout 0.1.0__py3-none-any.whl

github_reachout/__init__.py

@@ -0,0 +1,6 @@
+"""
+Github-reachout: GitHub 人才触达工具。
+
+获取 GitHub 信息 → 总结技术方向 → 生成触达邮件 → 发送
+"""
+__version__ = "0.1.0"

github_reachout/__main__.py

@@ -0,0 +1,5 @@
+"""允许 python -m github_reachout 运行。"""
+from github_reachout.cli import app
+
+if __name__ == "__main__":
+    app()

github_reachout/checkpoint.py

@@ -0,0 +1,227 @@
+"""
+Checkpoint 持久化模块。
+
+功能：
+  - 每个步骤完成后自动保存 state 到本地 JSON 文件
+  - 支持 --resume 从断点恢复运行
+  - 搜索到的人员单独保存为独立文件（方便查看和复用）
+
+存储结构：
+  .github_reachout_checkpoints/
+  └── {run_id}/
+      ├── state.json              # 完整 state 快照
+      ├── step_{n}_{name}.json    # 每步完成后的增量快照
+      └── persons/
+          ├── {login}.json        # 每个人的详细数据
+          └── all_persons.json    # 所有人汇总
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, Any, Optional
+
+
+# 默认 checkpoint 根目录
+DEFAULT_CHECKPOINT_DIR = ".github_reachout_checkpoints"
+
+
+def get_run_dir(run_id: str, base_dir: str = DEFAULT_CHECKPOINT_DIR) -> str:
+    """获取某次运行的 checkpoint 目录。"""
+    run_dir = os.path.join(base_dir, run_id)
+    os.makedirs(run_dir, exist_ok=True)
+    return run_dir
+
+
+def get_persons_dir(run_id: str, base_dir: str = DEFAULT_CHECKPOINT_DIR) -> str:
+    """获取人员存储目录。"""
+    person_dir = os.path.join(get_run_dir(run_id, base_dir), "persons")
+    os.makedirs(person_dir, exist_ok=True)
+    return person_dir
+
+
+def save_checkpoint(
+    state: Dict[str, Any],
+    step_name: str,
+    step_index: int,
+    run_id: str,
+    base_dir: str = DEFAULT_CHECKPOINT_DIR,
+) -> str:
+    """
+    保存 checkpoint：完整 state 快照 + 候选人独立文件。
+
+    Args:
+        state: 当前完整 state
+        step_name: 步骤名称（如 search, dedup, score 等）
+        step_index: 步骤序号
+        run_id: 运行 ID
+        base_dir: checkpoint 根目录
+
+    Returns:
+        保存的 checkpoint 文件路径
+    """
+    run_dir = get_run_dir(run_id, base_dir)
+
+    # 1. 保存步骤快照
+    step_file = os.path.join(run_dir, f"step_{step_index:03d}_{step_name}.json")
+    _write_json(step_file, state)
+
+    # 2. 更新最新 state（始终指向最新状态）
+    latest_file = os.path.join(run_dir, "state.json")
+    _write_json(latest_file, state)
+
+    # 3. 如果有人员数据，单独保存
+    persons = state.get("persons", [])
+    if persons and step_name in ("fetch", "enrich", "summarize"):
+        _save_persons(persons, run_id, base_dir)
+
+    # 4. 如果有邮件结果，也保存
+    sent_results = state.get("sent_results", [])
+    if sent_results and step_name in ("validate", "send"):
+        sent_file = os.path.join(run_dir, "sent_results.json")
+        _write_json(sent_file, sent_results)
+
+    return step_file
+
+
+def _save_persons(
+    persons: list,
+    run_id: str,
+    base_dir: str = DEFAULT_CHECKPOINT_DIR,
+) -> None:
+    """保存人员数据：汇总文件 + 独立文件。"""
+    person_dir = get_persons_dir(run_id, base_dir)
+
+    # 汇总文件
+    all_file = os.path.join(person_dir, "all_persons.json")
+    _write_json(all_file, persons)
+
+    # 独立文件（每个人一个 JSON）
+    for p in persons:
+        login = str(p.get("login") or p.get("id") or "unknown")
+        if login and login != "unknown":
+            p_file = os.path.join(person_dir, f"{login}.json")
+            # 不覆盖已有文件（去重后可能重复保存）
+            if not os.path.exists(p_file):
+                _write_json(p_file, p)
+
+
+def load_checkpoint(run_id: str, base_dir: str = DEFAULT_CHECKPOINT_DIR) -> Optional[Dict[str, Any]]:
+    """
+    加载最新的 checkpoint state。
+
+    Args:
+        run_id: 运行 ID
+        base_dir: checkpoint 根目录
+
+    Returns:
+        最新的 state dict，如果不存在返回 None
+    """
+    latest_file = os.path.join(get_run_dir(run_id, base_dir), "state.json")
+    if not os.path.isfile(latest_file):
+        return None
+    return _read_json(latest_file)
+
+
+def list_checkpoints(base_dir: str = DEFAULT_CHECKPOINT_DIR) -> list:
+    """
+    列出所有可恢复的 checkpoint 运行。
+
+    Returns:
+        [{"run_id": "...", "timestamp": "...", "step_count": N, "latest_step": "..."}]
+    """
+    if not os.path.isdir(base_dir):
+        return []
+
+    results = []
+    for run_id in os.listdir(base_dir):
+        run_dir = os.path.join(base_dir, run_id)
+        if not os.path.isdir(run_dir):
+            continue
+
+        state_file = os.path.join(run_dir, "state.json")
+        if not os.path.isfile(state_file):
+            continue
+
+        try:
+            state = _read_json(state_file)
+            # 统计步骤快照数
+            step_files = [f for f in os.listdir(run_dir) if f.startswith("step_") and f.endswith(".json")]
+            results.append({
+                "run_id": run_id,
+                "target_tech": state.get("target_tech_direction", "N/A"),
+                "loop_count": state.get("loop_count", 0),
+                "continue_loop": state.get("continue_loop", False),
+                "step_count": len(step_files),
+                "persons_count": len(state.get("persons", [])),
+                "sent_count": len(state.get("sent_results", [])),
+                "errors_count": len(state.get("errors", [])),
+            })
+        except Exception:
+            continue
+
+    return results
+
+
+def get_resume_info(run_id: str, base_dir: str = DEFAULT_CHECKPOINT_DIR) -> Optional[Dict[str, Any]]:
+    """
+    获取断点续跑信息：当前执行到哪一步、下一步应该执行什么。
+
+    Returns:
+        {"run_id": "...", "completed_steps": [...], "next_step": "...", "loop_count": N}
+    """
+    state = load_checkpoint(run_id, base_dir)
+    if not state:
+        return None
+
+    run_dir = get_run_dir(run_id, base_dir)
+    step_files = sorted([f for f in os.listdir(run_dir) if f.startswith("step_") and f.endswith(".json")])
+
+    completed_steps = []
+    for f in step_files:
+        # step_001_search.json -> search
+        parts = f.replace(".json", "").split("_", 2)
+        if len(parts) >= 3:
+            completed_steps.append(parts[2])
+
+    # 确定下一步
+    all_steps = ["plan", "fetch", "enrich", "summarize", "generate", "validate", "send", "evaluate"]
+    planned = state.get("planned_steps", all_steps)
+    next_step = None
+    for s in planned:
+        if s not in completed_steps:
+            next_step = s
+            break
+
+    return {
+        "run_id": run_id,
+        "completed_steps": completed_steps,
+        "next_step": next_step,
+        "loop_count": state.get("loop_count", 0),
+        "continue_loop": state.get("continue_loop", False),
+        "state": state,
+    }
+
+
+def cleanup_checkpoint(run_id: str, base_dir: str = DEFAULT_CHECKPOINT_DIR) -> None:
+    """删除某次运行的 checkpoint 数据。"""
+    import shutil
+    run_dir = os.path.join(base_dir, run_id)
+    if os.path.isdir(run_dir):
+        shutil.rmtree(run_dir)
+
+
+# ──────────────────────────────────────────────
+#  内部辅助
+# ──────────────────────────────────────────────
+
+def _write_json(path: str, data: Any) -> None:
+    """写入 JSON 文件。"""
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2, default=str)
+
+
+def _read_json(path: str) -> Any:
+    """读取 JSON 文件。"""
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)

github_reachout/cli.py

@@ -0,0 +1,232 @@
+"""
+Github-reachout CLI 入口。
+
+命令：
+  run     — 执行触达流程
+  resume  — 从断点恢复
+  list    — 列出所有 checkpoint
+  show    — 查看某次运行详情
+  cleanup — 删除 checkpoint
+"""
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import Path
+from typing import Optional, List
+
+import typer
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = typer.Typer(
+    name="github-reachout",
+    help="GitHub 人才触达工具：获取 GitHub 信息 → 总结技术方向 → 生成触达邮件 → 发送",
+    add_completion=False,
+)
+
+
+def _init_components(dry_run: bool = False):
+    """初始化所有组件。"""
+    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
+
+    llm = LLMClient()
+    github = GitHubClient()
+    web_reader = WebReader()
+    email_client = EmailClient()
+
+    if dry_run:
+        class DryRunEmailClient(EmailClient):
+            def send_email(self, to, subject, body, html=False):
+                typer.echo(f"  [DRY RUN] 邮件将发送给: {to}, 主题: {subject}")
+                return {"success": True, "error": ""}
+        email_client = DryRunEmailClient()
+
+    return llm, github, web_reader, email_client
+
+
+def _run_graph(state: dict, compiled_graph, run_id: str, step_index: int = 0) -> dict:
+    """执行图并保存 checkpoint，返回最终 state。"""
+    from github_reachout.checkpoint import save_checkpoint
+
+    try:
+        for output_state in compiled_graph.stream(state):
+            for node_name, node_output in output_state.items():
+                step_index += 1
+                typer.echo(f"\n── 步骤 {step_index}: {node_name} ──")
+                state.update(node_output)
+                save_checkpoint(state, node_name, step_index, run_id)
+    except KeyboardInterrupt:
+        typer.echo("\n\n中断！已保存 checkpoint，可用 --resume 恢复")
+        save_checkpoint(state, "interrupted", step_index, run_id)
+        raise typer.Exit(1)
+    except Exception as e:
+        typer.echo(f"\n运行出错: {e}")
+        save_checkpoint(state, "error", step_index, run_id)
+        raise typer.Exit(1)
+
+    return state
+
+
+def _print_summary(state: dict) -> None:
+    """打印运行结果摘要。"""
+    persons = state.get("persons", [])
+    errors = state.get("errors", [])
+
+    typer.echo("\n" + "=" * 60)
+    typer.echo("运行结果摘要")
+    typer.echo("=" * 60)
+    typer.echo(f"\n总人数: {len(persons)}")
+
+    for person in persons:
+        login = person.get("login", "?")
+        name = person.get("name", "") or login
+        tech = person.get("tech_direction", "unknown")
+        email_sent = person.get("email_sent", False)
+        no_email = person.get("no_email", False)
+        tech_mismatch = person.get("tech_mismatch", False)
+        email_ready = person.get("email_ready", False)
+
+        if email_sent:
+            status = "已发送"
+        elif no_email:
+            status = "无邮箱"
+        elif tech_mismatch:
+            status = "方向不匹配"
+        elif not email_ready:
+            status = "校验未通过"
+        else:
+            status = "待发送"
+
+        typer.echo(f"\n  {name} (@{login})")
+        typer.echo(f"    技术方向: {tech}")
+        typer.echo(f"    状态: {status}")
+        if person.get("email_body"):
+            typer.echo(f"    邮件主题: {person.get('email_subject', 'N/A')}")
+
+    if errors:
+        typer.echo(f"\n错误数: {len(errors)}")
+        for err in errors[:5]:
+            typer.echo(f"  - [{err.get('step', '?')}] {err.get('login', '?')}: {err.get('error', '?')}")
+    typer.echo("")
+
+
+@app.command()
+def run(
+    login_ids: List[str] = typer.Argument(..., help="GitHub login ID 列表"),
+    target_tech: str = typer.Option("", "--target-tech", "-t", help="目标技术方向"),
+    company: str = typer.Option("", "--company", "-c", help="我方公司名称"),
+    sender_name: str = typer.Option("", "--sender-name", "-n", help="发件人姓名"),
+    sender_title: str = typer.Option("", "--sender-title", help="发件人职位"),
+    max_loops: int = typer.Option(3, "--max-loops", "-l", help="最大循环次数"),
+    dry_run: bool = typer.Option(False, "--dry-run", "-d", help="试运行：不实际发送邮件"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出结果到 JSON 文件"),
+):
+    """执行 GitHub 人才触达流程。"""
+    from github_reachout.graph import build_graph, create_initial_state
+
+    # 从 .env 补全参数
+    sender_email = os.getenv("SENDER_EMAIL", "")
+    company = company or os.getenv("COMPANY_NAME", "")
+    sender_name = sender_name or os.getenv("SENDER_NAME", "")
+    sender_title = sender_title or os.getenv("SENDER_TITLE", "")
+    target_tech = target_tech or os.getenv("TARGET_TECH", "")
+
+    run_id = uuid.uuid4().hex[:8]
+
+    typer.echo(f"Github-reachout 启动 (run_id: {run_id})")
+    typer.echo(f"  目标人数: {len(login_ids)} | 技术方向: {target_tech or '未指定'} | 公司: {company or '未指定'}")
+    typer.echo(f"  发件人: {sender_name or '未指定'} | 最大循环: {max_loops} | 试运行: {'是' if dry_run else '否'}")
+
+    llm, github, web_reader, email_client = _init_components(dry_run)
+    compiled_graph = build_graph(llm, github, web_reader, email_client)
+
+    state = create_initial_state(
+        login_ids=login_ids, target_tech_direction=target_tech,
+        company_name=company, sender_name=sender_name,
+        sender_title=sender_title, sender_email=sender_email,
+        max_loops=max_loops, run_id=run_id,
+    )
+
+    state = _run_graph(state, compiled_graph, run_id)
+    _print_summary(state)
+
+    if output:
+        Path(output).write_text(json.dumps(state, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+        typer.echo(f"结果已保存到: {output}")
+
+
+@app.command()
+def resume(
+    run_id: str = typer.Argument(..., help="要恢复的运行 ID"),
+    dry_run: bool = typer.Option(False, "--dry-run", "-d", help="试运行"),
+):
+    """从断点恢复运行。"""
+    from github_reachout.graph import build_graph
+    from github_reachout.checkpoint import load_checkpoint
+
+    state = load_checkpoint(run_id)
+    if not state:
+        typer.echo(f"未找到运行 ID: {run_id}")
+        raise typer.Exit(1)
+
+    typer.echo(f"恢复运行 (run_id: {run_id})")
+    typer.echo(f"  已处理人数: {len(state.get('persons', []))} | 循环次数: {state.get('loop_count', 0)}")
+
+    llm, github, web_reader, email_client = _init_components(dry_run)
+    compiled_graph = build_graph(llm, github, web_reader, email_client)
+
+    state = _run_graph(state, compiled_graph, run_id, state.get("step_index", 0))
+    _print_summary(state)
+
+
+@app.command(name="list")
+def list_runs():
+    """列出所有可恢复的 checkpoint 运行。"""
+    from github_reachout.checkpoint import list_checkpoints
+
+    checkpoints = list_checkpoints()
+    if not checkpoints:
+        typer.echo("没有找到任何 checkpoint 运行记录")
+        return
+
+    typer.echo(f"{'Run ID':<12} {'技术方向':<16} {'循环':<6} {'步骤':<6} {'人数':<6} {'已发送':<8}")
+    typer.echo("-" * 56)
+    for cp in checkpoints:
+        typer.echo(
+            f"{cp.get('run_id', '?'):<12} "
+            f"{cp.get('target_tech', 'N/A'):<16} "
+            f"{cp.get('loop_count', 0):<6} "
+            f"{cp.get('step_count', 0):<6} "
+            f"{cp.get('persons_count', 0):<6} "
+            f"{cp.get('sent_count', 0):<8}"
+        )
+
+
+@app.command()
+def show(run_id: str = typer.Argument(..., help="运行 ID")):
+    """查看某次运行的详细信息。"""
+    from github_reachout.checkpoint import load_checkpoint
+
+    state = load_checkpoint(run_id)
+    if not state:
+        typer.echo(f"未找到运行 ID: {run_id}")
+        raise typer.Exit(1)
+    typer.echo(json.dumps(state, ensure_ascii=False, indent=2, default=str))
+
+
+@app.command()
+def cleanup(run_id: str = typer.Argument(..., help="要删除的运行 ID")):
+    """删除某次运行的 checkpoint 数据。"""
+    from github_reachout.checkpoint import cleanup_checkpoint
+    cleanup_checkpoint(run_id)
+    typer.echo(f"已删除运行 {run_id} 的 checkpoint 数据")
+
+
+if __name__ == "__main__":
+    app()

github_reachout/email_client.py

@@ -0,0 +1,158 @@
+"""
+邮件客户端模块。
+
+功能：
+  - 通过 SMTP 发送触达邮件
+  - 从 .env 读取邮箱配置
+  - 支持 HTML 和纯文本格式
+  - 发送前校验（无占位符、收件人有效）
+"""
+from __future__ import annotations
+
+import os
+import re
+import smtplib
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from typing import Optional, Dict, Any
+
+
+class EmailClient:
+    """SMTP 邮件客户端，用于发送触达邮件。"""
+
+    def __init__(
+        self,
+        smtp_host: Optional[str] = None,
+        smtp_port: Optional[int] = None,
+        smtp_user: Optional[str] = None,
+        smtp_password: Optional[str] = None,
+        sender_email: Optional[str] = None,
+        sender_name: Optional[str] = None,
+        use_ssl: Optional[bool] = None,
+    ):
+        """
+        Args:
+            smtp_host: SMTP 服务器地址
+            smtp_port: SMTP 服务器端口
+            smtp_user: SMTP 登录用户名
+            smtp_password: SMTP 登录密码/授权码
+            sender_email: 发件人邮箱地址
+            sender_name: 发件人姓名
+            use_ssl: 是否使用 SSL（默认根据端口判断）
+        """
+        self.smtp_host = smtp_host or os.getenv("SMTP_HOST", "smtp.gmail.com")
+        self.smtp_port = int(smtp_port or os.getenv("SMTP_PORT", "587"))
+        self.smtp_user = smtp_user or os.getenv("SMTP_USER", "")
+        self.smtp_password = smtp_password or os.getenv("SMTP_PASSWORD", "")
+        self.sender_email = sender_email or os.getenv("SENDER_EMAIL", self.smtp_user)
+        self.sender_name = sender_name or os.getenv("SENDER_NAME", "")
+        self.use_ssl = use_ssl if use_ssl is not None else (self.smtp_port == 465)
+
+    def send_email(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        html: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        发送一封邮件。
+
+        Args:
+            to: 收件人邮箱
+            subject: 邮件主题
+            body: 邮件正文
+            html: 是否为 HTML 格式
+
+        Returns:
+            {"success": bool, "error": str}
+        """
+        if not self.smtp_user or not self.smtp_password:
+            return {
+                "success": False,
+                "error": "SMTP 凭据未配置，请设置 SMTP_USER 和 SMTP_PASSWORD 环境变量",
+            }
+
+        if not to or "@" not in to:
+            return {"success": False, "error": f"无效的收件人邮箱: {to}"}
+
+        try:
+            msg = MIMEMultipart("alternative")
+            msg["From"] = f"{self.sender_name} <{self.sender_email}>" if self.sender_name else self.sender_email
+            msg["To"] = to
+            msg["Subject"] = subject
+
+            if html:
+                msg.attach(MIMEText(body, "html", "utf-8"))
+            else:
+                msg.attach(MIMEText(body, "plain", "utf-8"))
+
+            # 连接 SMTP 服务器并发送
+            if self.use_ssl:
+                server = smtplib.SMTP_SSL(self.smtp_host, self.smtp_port, timeout=30)
+            else:
+                server = smtplib.SMTP(self.smtp_host, self.smtp_port, timeout=30)
+                server.ehlo()
+                server.starttls()
+                server.ehlo()
+
+            server.login(self.smtp_user, self.smtp_password)
+            server.sendmail(self.sender_email, [to], msg.as_string())
+            server.quit()
+
+            return {"success": True, "error": ""}
+
+        except smtplib.SMTPAuthenticationError as e:
+            return {"success": False, "error": f"SMTP 认证失败: {e}"}
+        except smtplib.SMTPException as e:
+            return {"success": False, "error": f"SMTP 发送失败: {e}"}
+        except Exception as e:
+            return {"success": False, "error": f"邮件发送异常: {e}"}
+
+    @staticmethod
+    def validate_email_ready(email_body: str, subject: str = "", to: str = "") -> Dict[str, Any]:
+        """
+        校验邮件是否可以直接发送。
+
+        检查项：
+          1. 无占位符（如 {name}, [Company], {{xxx}} 等）
+          2. 收件人邮箱有效
+          3. 主题和正文不为空
+
+        Returns:
+            {"ready": bool, "issues": [str]}
+        """
+        issues = []
+
+        # 检查占位符
+        placeholder_patterns = [
+            r'\{[a-zA-Z_][a-zA-Z0-9_]*\}',      # {name}, {company}
+            r'\{\{[a-zA-Z_][a-zA-Z0-9_]*\}\}',   # {{name}}, {{company}}
+            r'\[[A-Z][A-Z_]*\]',                  # [NAME], [COMPANY]
+            r'<<[a-zA-Z_]+>>',                    # <<name>>
+        ]
+        for pattern in placeholder_patterns:
+            matches = re.findall(pattern, email_body)
+            if matches:
+                issues.append(f"邮件正文包含占位符: {matches}")
+
+        # 检查主题占位符
+        for pattern in placeholder_patterns:
+            matches = re.findall(pattern, subject)
+            if matches:
+                issues.append(f"邮件主题包含占位符: {matches}")
+
+        # 检查收件人
+        if to and "@" not in to:
+            issues.append(f"收件人邮箱无效: {to}")
+
+        # 检查非空
+        if not email_body.strip():
+            issues.append("邮件正文为空")
+        if subject and not subject.strip():
+            issues.append("邮件主题为空")
+
+        return {
+            "ready": len(issues) == 0,
+            "issues": issues,
+        }