overview.md

邮件智能分类 & Google Sheets 自动回填系统 — 交付概览

项目结构

wellfound-feedback/
├── app.py                    # Gradio 前端界面（入口）
├── src/
│   ├── config.py             # 环境变量配置管理
│   ├── email_parser.py       # .msg 邮件解析
│   ├── ai_classifier.py      # AI 分类（OpenAI/DeepSeek）
│   ├── sheets_updater.py     # Google Sheets 模糊匹配 + 写入
│   └── processor.py          # 处理管线（协调各模块）
├── requirements.txt          # Python 依赖
├── .env.example              # 环境变量模板（含详细注释）
├── .gitignore                # 安全排除 .env、密钥文件
├── space_config.md           # Hugging Face Space 元数据
└── README.md                 # 完整部署文档 + 用户操作手册

核心功能实现

📧 邮件解析（email_parser.py）

• extract-msg 解析 .msg 文件
• 提取：发件人邮箱、日期、主题、正文
• HTML 正文自动转纯文本（html2text）
• 从发件人域名提取备用公司名

🤖 AI 分类（ai_classifier.py）

• 支持 OpenAI（gpt-4o-mini）和 DeepSeek（deepseek-chat）
• 强制 JSON 输出，严格校验 8 种分类标签
• asyncio 异步 + Semaphore 并发控制
• tenacity 自动重试（3次，指数退避）
• 置信度评估（high / medium / low）

📊 Google Sheets 回填（sheets_updater.py）

• rapidfuzz token_sort_ratio 模糊匹配
• 可配置阈值（默认 85%）+ 歧义间隔（默认 3%）
• 三种匹配状态：exact / fuzzy / ambiguous / not_found
• 优先级覆盖策略：HIGH > LOW，同级保留最早数据
• 批量写入 AA/AB/AC/AD 列

🖥️ Gradio 界面（app.py）

• 拖拽多文件上传（.msg）
• 实时进度显示
• 结果表格（8列）
• ⚠️ 待确认区：下拉选框选择候选公司，一键确认回填
• 日志输出区（50行滚动）
• Google Sheets 连接状态测试

部署步骤（Hugging Face Spaces）

1. GitHub 新建仓库，推送此代码
2. HF Spaces 创建（SDK: Gradio），关联 GitHub 仓库
3. Settings → Secrets 配置：
   • LLM_PROVIDER = openai 或 deepseek
   • OPENAI_API_KEY 或 DEEPSEEK_API_KEY
   • GOOGLE_SERVICE_ACCOUNT_JSON（整个 JSON 内容）
   • GOOGLE_SHEET_ID
   • GOOGLE_SHEET_NAME
4. 等待自动部署，访问 Space URL

关键设计决策

问题	解决方案
公司名提取不准确	AI 提取 + 发件人域名双重后备
表格名称不统一	rapidfuzz 模糊匹配（85% 阈值）
同一公司多封回复	优先级矩阵（真人回复 > 自动回复）
API 调用失败	tenacity 3次重试 + 友好错误提示
大批量并发	asyncio.Semaphore(5) 排队处理
密钥安全	全部通过环境变量，.gitignore 排除 .env