cold-msg 0.1.0__py3-none-any.whl

cold_msg/__init__.py

@@ -0,0 +1,7 @@
+"""cold-msg: 招聘冷邮件智能生成工具"""
+
+__version__ = "0.1.0"
+
+from cold_msg.core.generator import generate_cold_email
+
+__all__ = ["generate_cold_email", "__version__"]

cold_msg/cli.py

@@ -0,0 +1,282 @@
+"""CLI 命令行接口模块
+
+基于 Typer 实现，提供以下命令：
+- cold-msg generate: 从简历文本生成冷邮件
+- cold-msg web: 启动 Web 界面
+- cold-msg config: 查看/管理配置
+- cold-msg jobs: 管理职位列表
+- cold-msg template: 管理邮件模板
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.json import JSON as RichJSON
+
+from cold_msg.core.config import (
+    ColdMsgConfig,
+    JobPosition,
+    EmailTemplate,
+    load_config,
+    save_config,
+    load_jobs_from_file,
+)
+from cold_msg.core.generator import generate_cold_email, ColdEmailResult
+
+app = typer.Typer(
+    name="cold-msg",
+    help="招聘冷邮件智能生成工具 - 基于候选人简历文本自动生成 Cold Email",
+    add_completion=False,
+)
+console = Console()
+
+
+def _load_cfg(config_file: Optional[Path] = None, env_file: Optional[Path] = None) -> ColdMsgConfig:
+    """加载配置的辅助函数"""
+    return load_config(env_file=env_file, config_file=config_file)
+
+
+@app.command()
+def generate(
+    resume: str = typer.Argument(..., help="候选人简历文本"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="LLM 模型名称"),
+    config_file: Optional[Path] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+    env_file: Optional[Path] = typer.Option(None, "--env", help=".env 文件路径"),
+    jobs_file: Optional[Path] = typer.Option(None, "--jobs", "-j", help="职位列表文件路径 (yaml/json)"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+    raw: bool = typer.Option(False, "--raw", help="输出原始 JSON"),
+):
+    """从简历文本生成冷邮件"""
+    cfg = _load_cfg(config_file, env_file)
+
+    jobs = cfg.jobs
+    if jobs_file:
+        jobs = load_jobs_from_file(jobs_file)
+
+    if not jobs:
+        console.print("[red]错误: 职位列表为空，请通过配置文件或 --jobs 指定职位列表[/red]")
+        raise typer.Exit(1)
+
+    with console.status("[bold green]正在生成冷邮件..."):
+        result = generate_cold_email(
+            resume_text=resume,
+            cfg=cfg,
+            jobs=jobs,
+            model=model,
+        )
+
+    if not result.match_job_title:
+        console.print("[yellow]候选人未匹配到合适职位[/yellow]")
+        if raw:
+            console.print_json(result.to_json())
+        raise typer.Exit(0)
+
+    if raw:
+        console.print_json(result.to_json())
+    else:
+        console.print(Panel(
+            result.email_content,
+            title=f"[bold green]推荐职位: {result.recommend_title}[/bold green]",
+            border_style="green",
+        ))
+
+    if output:
+        output.write_text(result.to_json(), encoding="utf-8")
+        console.print(f"[dim]结果已保存: {output}[/dim]")
+
+
+@app.command()
+def web(
+    host: Optional[str] = typer.Option(None, "--host", "-h", help="监听地址"),
+    port: Optional[int] = typer.Option(None, "--port", "-p", help="监听端口"),
+    config_file: Optional[Path] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+    env_file: Optional[Path] = typer.Option(None, "--env", help=".env 文件路径"),
+    debug: bool = typer.Option(None, "--debug/--no-debug", help="调试模式"),
+):
+    """启动 Web 界面"""
+    cfg = _load_cfg(config_file, env_file)
+
+    from cold_msg.web.app import create_app
+    application = create_app(cfg)
+
+    _host = host or cfg.flask_host
+    _port = port or cfg.flask_port
+    _debug = debug if debug is not None else cfg.flask_debug
+
+    console.print(f"[bold green]启动 ColdMsg Web 界面: http://{_host}:{_port}[/bold green]")
+    application.run(host=_host, port=_port, debug=_debug)
+
+
+@app.command(name="config")
+def config_cmd(
+    action: str = typer.Argument("show", help="操作: show / init / set"),
+    key: Optional[str] = typer.Argument(None, help="配置键名 (set 操作时使用)"),
+    value: Optional[str] = typer.Argument(None, help="配置值 (set 操作时使用)"),
+    config_file: Optional[Path] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+):
+    """查看或管理配置"""
+    cfg = _load_cfg(config_file)
+
+    if action == "show":
+        console.print(Panel(RichJSON(json.dumps(cfg.to_dict(), ensure_ascii=False, default=str)),
+                            title="[bold]当前配置[/bold]", border_style="blue"))
+    elif action == "init":
+        path = save_config(cfg, config_file)
+        console.print(f"[green]配置已初始化: {path}[/green]")
+    elif action == "set":
+        if not key or value is None:
+            console.print("[red]set 操作需要提供 key 和 value[/red]")
+            raise typer.Exit(1)
+        if hasattr(cfg, key):
+            setattr(cfg, key, value)
+            path = save_config(cfg, config_file)
+            console.print(f"[green]配置已更新: {key}={value}[/green]")
+            console.print(f"[dim]保存至: {path}[/dim]")
+        else:
+            console.print(f"[red]未知配置项: {key}[/red]")
+            raise typer.Exit(1)
+    else:
+        console.print(f"[red]未知操作: {action}，支持: show / init / set[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def jobs(
+    action: str = typer.Argument("list", help="操作: list / add / import / export"),
+    job_title: Optional[str] = typer.Option(None, "--title", "-t", help="职位名称 (add 时使用)"),
+    qualification: Optional[str] = typer.Option(None, "--qual", "-q", help="任职要求 (add 时使用)"),
+    location: Optional[str] = typer.Option(None, "--loc", "-l", help="工作地点 (add 时使用)"),
+    file: Optional[Path] = typer.Option(None, "--file", "-f", help="文件路径 (import/export 时使用)"),
+    config_file: Optional[Path] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+):
+    """管理职位列表"""
+    cfg = _load_cfg(config_file)
+
+    if action == "list":
+        if not cfg.jobs:
+            console.print("[yellow]职位列表为空[/yellow]")
+            return
+        for i, job in enumerate(cfg.jobs, 1):
+            console.print(f"[bold]{i}. {job.job_title}[/bold]")
+            console.print(f"   要求: {job.qualification}")
+            console.print(f"   地点: {job.location}")
+            console.print()
+    elif action == "add":
+        if not job_title:
+            console.print("[red]add 操作需要 --title[/red]")
+            raise typer.Exit(1)
+        new_job = JobPosition(
+            job_title=job_title,
+            qualification=qualification or "",
+            location=location or "",
+        )
+        cfg.jobs.append(new_job)
+        save_config(cfg, config_file)
+        console.print(f"[green]已添加职位: {job_title}[/green]")
+    elif action == "import":
+        if not file:
+            console.print("[red]import 操作需要 --file[/red]")
+            raise typer.Exit(1)
+        imported = load_jobs_from_file(file)
+        cfg.jobs.extend(imported)
+        save_config(cfg, config_file)
+        console.print(f"[green]已导入 {len(imported)} 个职位[/green]")
+    elif action == "export":
+        if not file:
+            console.print("[red]export 操作需要 --file[/red]")
+            raise typer.Exit(1)
+        data = {"jobs": [j.to_dict() for j in cfg.jobs]}
+        file.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        console.print(f"[green]已导出 {len(cfg.jobs)} 个职位至 {file}[/green]")
+    else:
+        console.print(f"[red]未知操作: {action}，支持: list / add / import / export[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def template(
+    action: str = typer.Argument("show", help="操作: show / set / preview / reset"),
+    field: Optional[str] = typer.Argument(None, help="模板字段名 (set 操作时使用)"),
+    value: Optional[str] = typer.Argument(None, help="字段值 (set 操作时使用)"),
+    config_file: Optional[Path] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+):
+    """管理邮件模板
+
+    模板字段列表:
+      sender_name   - 发件人姓名
+      team_name     - 招聘团队名称
+      company_desc  - 公司描述
+      greeting      - 称呼/开头 (支持 {FullName})
+      intro         - 自我介绍 (支持 {TeamName})
+      body          - 职位推荐正文 (支持 {CompanyDesc}, {JobTitle})
+      location_line - 职位地点行 (支持 {Location})
+      closing       - 结尾联系语
+      sign_off      - 祝颂语
+      signature     - 签名（默认使用发件人姓名）
+    """
+    cfg = _load_cfg(config_file)
+    tpl = cfg.email_template
+
+    if action == "show":
+        table = Table(title="邮件模板配置", show_header=True, header_style="bold blue")
+        table.add_column("字段", style="cyan", width=16)
+        table.add_column("当前值", style="white")
+        for key, val in tpl.to_dict().items():
+            table.add_row(key, str(val))
+        console.print(table)
+
+    elif action == "set":
+        if not field or value is None:
+            console.print("[red]set 操作需要提供 field 和 value[/red]")
+            raise typer.Exit(1)
+        if not hasattr(tpl, field):
+            console.print(f"[red]未知模板字段: {field}[/red]")
+            console.print(f"[dim]可用字段: {', '.join(tpl.to_dict().keys())}[/dim]")
+            raise typer.Exit(1)
+        setattr(tpl, field, value)
+        save_config(cfg, config_file)
+        console.print(f"[green]模板已更新: {field}={value}[/green]")
+
+    elif action == "preview":
+        parts = [
+            tpl.greeting,
+            tpl.intro,
+            "",
+            tpl.body,
+            "",
+            tpl.location_line,
+            "",
+            tpl.closing,
+            "",
+            tpl.sign_off,
+            tpl.signature,
+        ]
+        text = "\n".join(parts)
+        text = text.replace("{TeamName}", tpl.team_name)
+        text = text.replace("{CompanyDesc}", tpl.company_desc)
+        text = text.replace("{SenderName}", tpl.sender_name)
+        console.print(Panel(text, title="[bold]邮件模板预览[/bold]", border_style="green"))
+
+    elif action == "reset":
+        cfg.email_template = EmailTemplate()
+        save_config(cfg, config_file)
+        console.print("[green]邮件模板已恢复为默认值[/green]")
+
+    else:
+        console.print(f"[red]未知操作: {action}，支持: show / set / preview / reset[/red]")
+        raise typer.Exit(1)
+
+
+def main():
+    """CLI 入口"""
+    app()
+
+
+if __name__ == "__main__":
+    main()

cold_msg/core/__init__.py

@@ -0,0 +1,8 @@
+"""核心模块：配置、提示词、LLM调用、邮件生成"""
+
+from cold_msg.core.config import ColdMsgConfig, load_config
+from cold_msg.core.generator import generate_cold_email
+from cold_msg.core.prompt import build_prompt
+from cold_msg.core.llm import call_llm
+
+__all__ = ["ColdMsgConfig", "load_config", "generate_cold_email", "build_prompt", "call_llm"]

cold_msg/core/config.py

@@ -0,0 +1,215 @@
+"""配置管理模块
+
+负责加载和管理 cold-msg 的所有配置项，包括：
+- LLM 配置（通过 llmdog）
+- 职位列表配置
+- 邮件模板配置
+- Web 服务配置
+"""
+
+import json
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from dotenv import load_dotenv
+
+
+@dataclass
+class JobPosition:
+    """单个职位信息"""
+    job_title: str
+    qualification: str
+    location: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class EmailTemplate:
+    """邮件模板配置
+
+    所有字段均可自定义，用于控制生成邮件的各个组成部分。
+    模板中使用 {占位符} 标记变量，运行时由系统替换。
+    """
+    sender_name: str = "Michael"
+    team_name: str = "高端招聘团队"
+    company_desc: str = "国际知名大型科技公司"
+
+    greeting: str = "您好{FullName}，"
+    intro: str = "我来自{TeamName}，很冒昧的给您发邮件。通过Linkedin了解到您，了解到您在XXX, XXX等方向有丰富经验。"
+    body: str = "我负责{CompanyDesc}招聘，非常希望邀请到您这样的人才在此向您推荐\"{JobTitle}\"的职位。负责带领技术团队攻克更多XXX，XXX技术难题，进一步提升您在行业内的影响力。"
+    location_line: str = "职位地点： {Location}"
+    closing: str = "如果您有兴趣具体了解的话，可以留个电话或者微信，给您详细介绍一下，期待与您的沟通~"
+    sign_off: str = "祝颂商祺"
+    signature: str = "Michael"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ColdMsgConfig:
+    """cold-msg 完整配置"""
+    sender_name: str = "Michael"
+    team_name: str = "高端招聘团队"
+    company_desc: str = "国际知名大型科技公司"
+
+    llm_model: str = "deepseek-v3.1-terminus"
+
+    flask_host: str = "127.0.0.1"
+    flask_port: int = 6060
+    flask_debug: bool = True
+
+    jobs: list[JobPosition] = field(default_factory=list)
+
+    email_template: EmailTemplate = field(default_factory=EmailTemplate)
+
+    config_dir: Path = field(default_factory=lambda: Path.cwd())
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["config_dir"] = str(self.config_dir)
+        return d
+
+
+def _env_bool(val: Optional[str], default: bool = False) -> bool:
+    """将环境变量字符串转为布尔值"""
+    if val is None:
+        return default
+    return val.lower() in ("1", "true", "yes")
+
+
+def load_config(
+    env_file: Optional[Path] = None,
+    config_file: Optional[Path] = None,
+) -> ColdMsgConfig:
+    """加载配置
+
+    优先级（从高到低）：
+    1. 环境变量
+    2. .env 文件
+    3. 配置文件 (./config.yaml)
+    4. 内置默认值
+
+    Args:
+        env_file: 指定 .env 文件路径，默认自动搜索
+        config_file: 指定配置文件路径，默认使用 ./config.yaml
+
+    Returns:
+        ColdMsgConfig 实例
+    """
+    if env_file and env_file.exists():
+        load_dotenv(env_file)
+    else:
+        for p in [Path(".env"), Path.cwd() / ".env"]:
+            if p.exists():
+                load_dotenv(p)
+                break
+
+    file_config: dict = {}
+    if config_file and config_file.exists():
+        with open(config_file, "r", encoding="utf-8") as f:
+            if config_file.suffix in (".yaml", ".yml"):
+                file_config = yaml.safe_load(f) or {}
+            elif config_file.suffix == ".json":
+                file_config = json.load(f)
+    else:
+        default_config = Path.cwd() / "config.yaml"
+        if default_config.exists():
+            with open(default_config, "r", encoding="utf-8") as f:
+                file_config = yaml.safe_load(f) or {}
+
+    cfg = ColdMsgConfig(
+        sender_name=os.getenv("COLDMSG_SENDER_NAME", file_config.get("sender_name", ColdMsgConfig.sender_name)),
+        team_name=os.getenv("COLDMSG_TEAM_NAME", file_config.get("team_name", ColdMsgConfig.team_name)),
+        company_desc=file_config.get("company_desc", ColdMsgConfig.company_desc),
+        llm_model=os.getenv("LLM_MODEL", file_config.get("llm_model", ColdMsgConfig.llm_model)),
+        flask_host=os.getenv("FLASK_HOST", file_config.get("flask_host", ColdMsgConfig.flask_host)),
+        flask_port=int(os.getenv("FLASK_PORT", file_config.get("flask_port", ColdMsgConfig.flask_port))),
+        flask_debug=_env_bool(os.getenv("FLASK_DEBUG"), file_config.get("flask_debug", ColdMsgConfig.flask_debug)),
+    )
+
+    jobs_data = file_config.get("jobs", [])
+    cfg.jobs = [
+        JobPosition(
+            job_title=j.get("job_title", j.get("JobTitle", "")),
+            qualification=j.get("qualification", j.get("Qualification", "")),
+            location=j.get("location", j.get("Location", "")),
+        )
+        for j in jobs_data
+    ]
+
+    tpl_data = file_config.get("email_template", {})
+    if tpl_data:
+        cfg.email_template = EmailTemplate(**tpl_data)
+
+    return cfg
+
+
+def save_config(cfg: ColdMsgConfig, config_file: Optional[Path] = None) -> Path:
+    """保存配置到文件
+
+    Args:
+        cfg: 配置实例
+        config_file: 指定保存路径，默认 ./config.yaml
+
+    Returns:
+        保存的文件路径
+    """
+    if config_file is None:
+        config_file = cfg.config_dir / "config.yaml"
+
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+
+    data = {
+        "sender_name": cfg.sender_name,
+        "team_name": cfg.team_name,
+        "company_desc": cfg.company_desc,
+        "llm_model": cfg.llm_model,
+        "flask_host": cfg.flask_host,
+        "flask_port": cfg.flask_port,
+        "flask_debug": cfg.flask_debug,
+        "jobs": [j.to_dict() for j in cfg.jobs],
+        "email_template": cfg.email_template.to_dict(),
+    }
+
+    with open(config_file, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, allow_unicode=True, default_flow_style=False, sort_keys=False)
+
+    return config_file
+
+
+def load_jobs_from_file(filepath: Path) -> list[JobPosition]:
+    """从外部文件加载职位列表
+
+    支持 YAML 和 JSON 格式。
+
+    Args:
+        filepath: 文件路径
+
+    Returns:
+        职位列表
+    """
+    with open(filepath, "r", encoding="utf-8") as f:
+        if filepath.suffix in (".yaml", ".yml"):
+            data = yaml.safe_load(f) or []
+        elif filepath.suffix == ".json":
+            data = json.load(f)
+        else:
+            raise ValueError(f"不支持的文件格式: {filepath.suffix}，请使用 yaml/yml/json")
+
+    if isinstance(data, dict):
+        data = data.get("jobs", data.get("positions", []))
+
+    return [
+        JobPosition(
+            job_title=j.get("job_title", j.get("JobTitle", "")),
+            qualification=j.get("qualification", j.get("Qualification", "")),
+            location=j.get("location", j.get("Location", "")),
+        )
+        for j in data
+    ]

cold_msg/core/generator.py

@@ -0,0 +1,129 @@
+"""邮件生成器模块
+
+核心业务逻辑：组合配置、提示词构建、LLM 调用，生成最终的冷邮件。
+"""
+
+import json
+import logging
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Optional
+
+from cold_msg.core.config import ColdMsgConfig, JobPosition, EmailTemplate, load_config, load_jobs_from_file
+from cold_msg.core.prompt import build_prompt
+from cold_msg.core.llm import call_llm
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ColdEmailResult:
+    """冷邮件生成结果"""
+    match_job_title: bool = False
+    recommend_title: str = ""
+    email_content: str = ""
+    raw_response: dict | None = None
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        return d
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    @classmethod
+    def from_llm_response(cls, data: dict) -> "ColdEmailResult":
+        """从 LLM 返回的字典构建结果"""
+        return cls(
+            match_job_title=data.get("match_job_title", False),
+            recommend_title=data.get("recommend_title", ""),
+            email_content=data.get("email_content", ""),
+            raw_response=data,
+        )
+
+
+def generate_cold_email(
+    resume_text: str,
+    cfg: Optional[ColdMsgConfig] = None,
+    jobs: Optional[list[JobPosition]] = None,
+    email_template: Optional[EmailTemplate] = None,
+    custom_prompt: Optional[str] = None,
+    model: Optional[str] = None,
+) -> ColdEmailResult:
+    """生成冷邮件
+
+    这是 cold-msg 的核心入口函数，既可被 CLI 调用，也可被 Web 调用，
+    也可以作为 Python 库直接调用。
+
+    Args:
+        resume_text: 候选人简历文本
+        cfg: 配置实例，为 None 时自动加载
+        jobs: 职位列表，为 None 时使用配置中的职位列表
+        email_template: 邮件模板，为 None 时使用配置中的模板
+        custom_prompt: 自定义提示词
+        model: 指定 LLM 模型
+
+    Returns:
+        ColdEmailResult 实例
+    """
+    if cfg is None:
+        cfg = load_config()
+
+    if jobs is None:
+        jobs = cfg.jobs
+
+    if email_template is None:
+        email_template = cfg.email_template
+
+    if not resume_text or not resume_text.strip():
+        logger.warning("简历文本为空")
+        return ColdEmailResult()
+
+    if not jobs:
+        logger.warning("职位列表为空，无法生成邮件")
+        return ColdEmailResult()
+
+    prompt = build_prompt(
+        resume_text=resume_text,
+        jobs=jobs,
+        email_template=email_template,
+        custom_prompt=custom_prompt,
+    )
+
+    result_dict = call_llm(prompt, cfg, model=model)
+
+    if not result_dict:
+        return ColdEmailResult()
+
+    return ColdEmailResult.from_llm_response(result_dict)
+
+
+def generate_cold_email_from_file(
+    resume_file: Path,
+    output_dir: Optional[Path] = None,
+    cfg: Optional[ColdMsgConfig] = None,
+    jobs: Optional[list[JobPosition]] = None,
+    model: Optional[str] = None,
+) -> ColdEmailResult:
+    """从简历文件生成冷邮件并保存结果
+
+    Args:
+        resume_file: 简历文本文件路径
+        output_dir: 输出目录，为 None 时不保存文件
+        cfg: 配置实例
+        jobs: 职位列表
+        model: 指定 LLM 模型
+
+    Returns:
+        ColdEmailResult 实例
+    """
+    resume_text = resume_file.read_text(encoding="utf-8")
+    result = generate_cold_email(resume_text, cfg=cfg, jobs=jobs, model=model)
+
+    if output_dir and result.match_job_title:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        output_file = output_dir / f"{resume_file.stem}.json"
+        output_file.write_text(result.to_json(), encoding="utf-8")
+        logger.info("结果已保存: %s", output_file)
+
+    return result