每日投稿邮箱统计（公用版）

当用户说「统计昨天/某天的邮箱」「每日收稿统计」「投稿汇总」「邮件附件统计」时，用本技能。流程已端到端跑通并固化所有坑点。本版自包含、无硬编码路径/账号，任何人导入填自己的邮箱即可用。

触发示例（用户原话 → AI 动作）

• 用户：「帮我统计昨天邮箱收到的投稿」 / 「收稿汇总」 / 「邮件附件统计一下」 AI：运行 node scripts/run.mjs <日期>（缺省=今天）→ 自动下载邮件附件 → 提取作者/作品/单位/电话 → 生成 Excel(4 表) + PDF(含历史回顾与图片预览) → 全套放到桌面 ~/Desktop/邮件附件/YYYY-MM-DD/。最后告诉你文件在哪、Excel 叫什么、PDF 叫什么。

• 用户：「看看 2026-07-15 那天收了多少件投稿」 AI：同上，日期传 2026-07-15，产出当天报表。

• 用户：「今天投稿的人里，有没有重复投稿的？都什么单位？」 AI：先跑上述流程生成报表，再基于 Excel 的「作品信息」「统计摘要」回答单位分布、重复/多版本归并情况。

一句话：只要提到「统计/汇总 + 邮箱/收稿/投稿 + （某天）」，就用本技能。不会用就直接说「统计某天邮箱」，AI 会接手剩下的。

别人拿这个可以做什么（通用适用场景）

本技能不是为某次活动定制的，而是一套**「按日期从邮箱拉取附件 → 归并统计 → 出 Excel/PDF 报表」的通用管线**。任何存在「某邮箱每天收到带附件的投稿/提交邮件、需要按人归并盘点」的场景都能直接套用，填自己的邮箱即可。典型用途：

• 征稿 / 收稿盘点：比赛、刊物、专栏、活动等有公开投稿邮箱的场景，每日/每期统计收到多少件、哪些作者、哪些单位、联系方式，附作品图预览。
• 活动报名 / 资料收集：某个活动邮箱收集报名表、作品、证件照、证明材料，自动归并出名单与附件清单。
• 摄影 / 设计 / 视频投稿：把图片、设计稿、视频封面等作为附件投稿，按投稿人归并、只计图像件数、文末附图预览。
• 简历 / 作品集收集：招聘或合作邮箱收到的简历 PDF、作品集附件，按发件人归并、统计收到数量。
• 订单 / 报表 / 单据附件回收：业务邮箱每日收到带附件的订单、对账单、票据扫描件，按 sender 归并出每日明细。
• 任何「按到达日盘点某邮箱附件」的需求：只要邮件带来附件、需要按人/按天汇总，都能复用这条链路（统计口径可在 extract_workinfo.mjs / generate_email_report.mjs 调整）。

通用点：① 邮箱完全参数化（SUB_EMAIL_*）；② 交付目录、历史页起始日、活动名称均可环境变量配置；③ 正文/主题/附件名/附件内 .docx 四路提取作者·作品·单位·电话·说明，适配大多数投稿表单；④ 网易/发票等系统邮件与压缩包有既定过滤与手动补录流程。

成品长什么样（样例预览）

以下截图来自用假数据（3 封投稿 / 4 张图片）跑真实脚本生成的样例。你的实际产出会按同样格式、包含你邮箱的真实投稿数据。 完整样例文件见 docs/sample/ 目录。

PDF 封面——当日统计概览

Excel 四表中的两页：作品信息表 + 附件明细表

PDF 文末：作品图片预览（每张投稿原图按收稿顺序排列）

Excel 四表结构速查

配置（自包含，无硬编码）

• 工作区 = 脚本目录：scripts/ 内的 5 个脚本互相依赖，中间产物（email_data_YYYY-MM-DD.json / attachments/）都生成在 scripts/ 内，整体可迁移。
• 邮箱：在 scripts/.env 填 SUB_EMAIL_IMAP_HOST / SUB_EMAIL_ACCOUNT / SUB_EMAIL_AUTH_CODE（模板见 .env.example）。支持 126/163/qq/gmail 等标准 IMAP 邮箱。
• 桌面交付目录：SUB_DESKTOP_DIR，默认 ~/Desktop/邮件附件（Excel/PDF/原图放 <根>/YYYY-MM-DD/）。
• 历史回顾页起始日：SUB_HISTORY_START_DATE（如 2026-07-09）；未设置则不生成历史回顾页。
• 活动/征集名称（可选）：SUB_EVENT_NAME，在 PDF 封面与页脚展示（如某征稿活动名）；留空则用通用标题「投稿作品收稿汇总」。

⚠️ 强制顺序（脚本依赖上一步产物，不可跳步/乱序）

推荐用法（一条命令全自动）：node scripts/run.mjs YYYY-MM-DD（缺省=今天）。运行器会依次跑完下面全部步骤，并自动把 Excel/PDF/原图交付到桌面 ~/Desktop/邮件附件/YYYY-MM-DD/，无需手动逐步执行、也不用手动复制文件。下面的 7 步保留作分步排查 / 高级用法。

1. 下载：node download_via_imap.mjs YYYY-MM-DD → 附件源存 scripts/attachments/<日期>/
2. 补正文：node fetch_text_bodies.mjs <日期>
3. 提信息：node extract_workinfo.mjs <日期>（从正文/主题/附件名填 author/work/unit/phone；并读取附件中的 .docx 投稿说明（jszip 解 word/document.xml），抽「创作年份+作品说明」写入 e.workYear/e.workDesc，主提取缺字段("—")时回退 docx 的姓名/作品/电话/单位）
4. 网易剔除：下载后滤掉 senderName.startsWith("网易") || senderEmail.endsWith("@service.netease.com")；不能按 @126/@163 域名一刀切（投稿人用这些域名）
5. 生成 Excel：node generate_email_report.mjs <日期> → 输出 邮件附件统计_YYYY-MM-DD.xlsx（scripts/ 内）
6. 生成 PDF（带历史页，必须用这个）：python generate_summary_pdf_from_xlsx.py <桌面xlsx路径> <桌面pdf路径>
   • ⚠️ xlsx 必须与投稿原图同目录（即桌面日期目录）：脚本用 os.path.dirname(xlsx路径) 定位原图去嵌入 PDF。先把 xlsx cp 到桌面日期目录、再传该绝对路径
7. 桌面交付：cp Excel + PDF + 各投稿原图 到 ~/Desktop/邮件附件/YYYY-MM-DD/（三者同目录）；网易残留 null_*.pdf 不复制

Excel 四表结构（generate_email_report.mjs 产出）

1. 邮件总览：邮件级信息
2. 附件明细：序号/日期/发件人/主题/摘要/文件名/大小/格式/状态/图片预览。图片嵌入用 addImage 按比例缩放
3. 作品信息：序号/日期/作者/作品/作品说明/单位/电话/件数（共 8 列；作品说明=docx 投稿说明，组合为「YYYY年｜说明文字」，无 docx 则"—"；件数=该人图像附件数）
4. 统计摘要

• 按 senderEmail 小写归并：同一人多邮件/多附件 → 一人一行、发件人只显一次
• 多作品名去重后用「、」连接
• 显示名回退：senderName 为纯数字(QQ号)/邮箱时回退 e.author

统计口径

• 日期归属 = 邮箱到达日：每封邮件归入其「到达邮箱的日期」（IMAP INTERNALDATE = 脚本 targetDate），不按邮件 Date 头的发送日。已下载的旧 JSON 若还存着发送日，需批量把每封 dateStr/date 校正为文件名对应日期
• 统计数字只计图像（jpg/jpeg/png/heic）：附件明细/统计摘要/历史页累计都只数图像；作品件数也只计图像附件
• 文档（docx 等）与压缩包仍全部下载并保存在日期目录内。docx 投稿说明由 extract_workinfo.mjs 读取，抽「创作年份+作品说明」填入作品信息表「作品说明」列（格式「YYYY年｜说明文字」）；均不计入件数/大小等统计数字
• 不做自动图片去重（所有附件原样保留）

PDF 字叠加修复

• 根因：表格单元格用普通字符串，reportlab 不自动换行 → 长内容溢出相邻列导致字叠加
• 修法：所有单元格文字改用 Paragraph(wordWrap='CJK') 按中文字符换行；表头 n 转为

• ⚠️ 勿回退为纯字符串单元格

常见问题与排错

普通使用遇到问题（授权码、乱码、超大附件、断点续传等），请直接看 INSTALL.md 的「常见问题 FAQ」，那里有白话解答。下面仅保留开发者/维护者才需要关心的固化技术备注，普通用户可跳过。

开发者/维护者备注（已修，固化后勿回退）

• ExcelJS mergeCells 永久弃用：合并会清空锚点单元格值。一律改「留空法」：同人首行写值、后续行空
• 无扩展名附件格式错识：path.extname 抓到文件名随机串 → format 乱码、图片无法嵌入。已加 detectFormatByMagic() 魔数兜底（download 和 generate 都做）
• 撞名附件跨邮件覆盖（已修，固化勿回退）：
  • 根因：download_via_imap.mjs 保存附件时只用原始文件名拼路径（outDir/原始名）。不同邮件的同名附件（如多人都叫 0714_1.jpg、0619_1.jpg、33D36900@….jpg）保存到同一路径，后下载的覆盖先下载的 → 跨邮件错配。曾导致投稿人A《作品甲》的 0714_1.jpg 被投稿人B同名图覆盖，表格里投稿人A挂着别人的图、磁盘少了一张真图。
  • 修法：给附件文件名加 IMAP uid 前缀（String(uid) + '_' + path.basename(原始名).replace(/[/\]/g,'_')），物理文件名全局唯一，彻底杜绝覆盖。两处都要改：①保存新附件处；②断点复用核对 existingPath 处（downloadPart(uid, att) 已带 uid，作用域覆盖两处）。
  • 验证口径：重下后跨 uid 的 MD5 重复对必须为 0（即不存在两个不同发件人字节相同=不可能再覆盖）；同内容对子若仍在，必全部落在同一 uid=同一封邮件内（来源本就重复），由附件级 MD5 去重标记 a.duplicate，磁盘原样保留、不删。
  • ⚠️ 交付表格若发现某人挂着别人的图 / 同名文件错配，第一反应查撞名覆盖，不要去怪数据源或手动改表。
• 同人同名作品去重（留大弃小）：
  • 场景：同一投稿人通过多封邮件投递同一作品的多个版本（不同分辨率/尺寸/格式），MD5 不同所以字节级去重抓不到。如投稿人A两封各投《作品甲》2.85MB 和 1.78MB。
  • 执行位置：extract_workinfo.mjs，在 MD5 字节级去重 → 邮件级去重之后（三级级联的第三级）。只对图像附件生效。
  • 依赖下载说明（重要）：当前两级去重都在「全部下载完成后」的 extract_workinfo.mjs 里做。MD5 字节级必须下载（要算文件哈希）；同名作品级当前读 a.localPath 的 size 也依赖下载。但原理上同名作品这一级可不下载就判定——IMAP BODYSTRUCTURE 的 part.size 已返回每个附件字节大小（不下传内容），作品名从邮件主题/正文解析也不依赖附件，故可做到"先选保留项、再只下那张"。当前脚本未做"先判后下"优化，仍是先全下后判；MD5 级则无论如何都要下载才能比对。
  • 判定逻辑：按 senderEmail 分组 → 每人收集非 duplicate 图像附件的归一化作品名（去《》""''书名号+去空格）→ 聚类（完全相同 / 编辑距离≤min(2,len×0.2) / 短串占长串≥70%）→ 每簇按文件大小降序，保留最大的，其余标记 a.duplicate=true + duplicateReason='same-work-smaller'。
  • 边界：不同人的同名作品不去重；同人的不同作品不去重（只合并"同一作品多版本"）。
  • 效果：Excel 附件明细该人只显示最大的一张；作品件数也只计保留项；PDF 只嵌入大图。
  • ⚠️ 交付前清理磁盘：被标记 a.duplicate 的多余原图必须从桌面目录删除（用户要求桌面只留有效附件）。删前先从 email_data 提取所有 duplicate && localPath 的 basename 列表，逐个 rm；保留项天然不在名单内。清理后桌面图片数 = Excel 附件明细行数。
• extract_workinfo 六坑：
  • ①零宽字符 u200b-u200fufeff 阻断单位提取
  • ②unitM 未复用 term 变量缺"地址"边界
  • ③未清 HTML 实体（  等）导致作者提取失败
  • ④subject 作者《作品》中间空格未兼容
  • ⑤无《》文件名当作者：文件名无 《》 时，原把文件名（通常是作品名）误赋给 author → 改为：无《》时文件名当 work、author 从 subject 开头取中文名
  • ⑥正文标签不全 + xa0 杂音：work 标签只认 作品(?:名称)? 不认 画作名称/画名 → 扩展；term 终止符缺 联系 → 正文"某某联系手机：136…"的 xa0 被当分隔导致 author 多出"联系"→ term 加 联系手机|联系
• workName 占位符"—"短路：原 e.workName || e.work 把占位符"—"当真值 → 改为非"—"才优先 e.work
• 文本段判定：node-imap 的 type 是小写 text/image，须 .toUpperCase()==='TEXT'
• PDF 字叠加：reportlab 单元格普通字符串不自动换行 → 全改 Paragraph(wordWrap='CJK')，表头 n 转

• PDF 路径坑：generate_summary_pdf_from_xlsx.py 用 dirname(xlsx) 定位原图——传工作区相对路径会因空串报错。必须先把 xlsx 放到桌面日期目录再传绝对路径
• docx 投稿说明必须抽取：原 extract_workinfo.mjs 完全不解析 .docx，导致投稿人「作品信息.docx」里的创作年份、作品说明长文从未进报表。现用 jszip 读 word/document.xml，parseDocxInfo 抽 创作年份/作品说明/姓名/作品/电话/单位 → 写 e.workYear/e.workDesc，主提取缺字段("—")时回退。⚠️ extract_workinfo.mjs 是 ESM，jszip 须从 NODE_MODULES_DIR（SUB_NODE_MODULES 或 WorkBuddy managed 环境）require；主循环为 async IIFE 以 await 读 docx
• 作品信息表「作品说明」列 + PDF work_rows 重建坑：作品信息表新增第 5 列「作品说明」后列序变为 序号/日期/作者/作品/作品说明/单位/电话/件数（8 列）。PDF 脚本在内部把 Excel 行重建成 work_rows，原代码只取前 7 列、且列序按旧布局——会列错位 + w[7] 越界。必须同步：①重建取满 8 列且按新列序；②作品信息表表头与 colWidths 对齐（现 [10,20,24,30,34,26,20,10]=174mm，顶满不可再加列）
• 超大附件通知邮件重跑 extract 会丢数据：类似「QQ 超大附件通知」的邮件正文是"资料已压缩打包…请查收"，自动提取不出正确作者/作品。一旦重跑 extract_workinfo.mjs 会把手动注入值冲掉、自动抽成乱码。修法：重跑 extract 后，对这类邮件手动把 author/workName/unit/phone 还原。长期应在 extract 里对"超大附件通知"邮件跳过自动提取（当前以手动还原为准）。通用处理：用户手动下载超大附件压缩包后，用 Python zipfile（cp437→gbk 解码）解包，再手动补写该邮件的 author/workName/unit/phone

过滤规则（两项都强制剔除）

• ①网易系统邮件：senderName.startsWith("网易") || senderEmail.endsWith("@service.netease.com")（脚本已实现）
• ②发票类邮件（必须做）：
  • 判定关键词——subject 含「发票 / 电子发票 / 增值税 / 专票 / 普票 / 开票 / 报销 / 发票代码 / 账单 / Invoice」之一，或 senderName/email 指向开票/财务系统
  • 实现方式：在「提信息」步骤前，对 email_data_<日期>.json 做整封剔除（可按关键词 grep 后从 json 中删除该记录，再跑后续脚本）；不要只靠肉眼，凡命中关键词即剔
• 保留：个人投稿邮件（含 @126/@163 投稿人）；广告/推广类按主题关键词轻量过滤，主要靠人工判断
• ⚠️ 不能按 @126/@163 域名一刀切（投稿人用这些域名）

压缩包处理

• 普通 .zip（走 IMAP 下载成功的邮件内联压缩包，如 126/163 个人邮箱发的）现已自动解包并入统计：下载流程在写盘后用 jszip + iconv-lite（GBK 解码文件名）自动解包，里面的图片按图像计件数、里面的 .docx 由 extract_workinfo 自动读内容填表，全部按发件人归并，无需手动处理。
• 网页托管的「超大附件 / 文件中转站」（QQ、网易）无法自动下载：这类附件不走 IMAP、需网页登录态手动下载。run.mjs 跑完会自动检测并提示这类「超大附件通知」邮件，给出处理步骤：① 网页端下载解压 → ② 把里面图片/文档放进桌面交付目录 ~/Desktop/邮件附件/YYYY-MM-DD/ → ③ 重跑 run.mjs（自动复用已有数据）或由 AI 手动补录。这属于客观限制，不追求全自动。
• 解包后文件执行与附件相同的规则（读文档内容填表、图像计件数、按发件人归并）

桌面交付规则

• Excel(邮件附件统计_YYYY-MM-DD.xlsx)、PDF(投稿作品汇总_YYYY-MM-DD.pdf)、投稿原图都必须在 ~/Desktop/邮件附件/YYYY-MM-DD/ 日期目录内（与源附件同目录）
• 即使工作区也生成，cp 到桌面是必需收尾；网易系统邮件残留 null_*.pdf 不复制
  • 交付前必须删除 email_data 中 a.duplicate=true 对应的多余原图文件（保留版已在表格/PDF 显示）；删前列出 duplicate 的 localPath basename 逐一 rm，保留项自然跳过。清理后桌面图片数须 = Excel 附件明细行数
  • 删除交互约定（与用户约定于 2026-07-17，已固化）：删除 duplicate 多余原图属不可逆操作。首次执行该删除时必须列出待删清单并告知操作者，并提示其选择「默认以后都这样（不再问）」或「次次提醒」。用户已选「默认以后都这样」——故此后删除时 AI 直接执行，但仍须把待删清单打印到日志/输出（非阻塞）供事后追溯，不再弹窗确认。⚠️ 该约定仅限本技能「交付前清理 duplicate 原图」这一特定动作；其他任意个人文件删除仍须遵循个人文件安全规则的确认要求，不泛化。

生成后验证清单（交付前强制自检）

• Excel 4 表齐全：邮件总览/附件明细/作品信息/统计摘要
• 附件明细「发件人」列无整列空白（mergeCells 已弃用）
• Excel 无"—"误显（workName 处理正确）
• Excel 图片嵌入数 = 实际图像附件数
• PDF 含历史回顾页（用 from_xlsx 脚本且设了 SUB_HISTORY_START_DATE），累计数字合理
• 桌面目录齐全：Excel + PDF + 各投稿原图，无 null_*.pdf 残留
  • 磁盘已清理重复：email_data 中 a.duplicate 的多余原图已从桌面目录删除，桌面图片数 = Excel 附件明细行数（本例 20→14）
• 无撞名覆盖：附件文件名均带 uid_ 前缀；抽查一个多人共有的同名文件（如 0714_1.jpg）在表格中应指向其本人 uid 的文件、而非别人；跨 uid 的 MD5 重复对应为 0
• PDF 列宽之和 ≤174mm（防右侧静默截断）；作品信息表现 8 列 [10,20,24,30,34,26,20,10]，加列须重分配
• 作品信息表「作品说明」列：有 docx 投稿说明的投稿人应显示「YYYY年｜说明」，无则"—"

迁移/安装

• 用户级技能目录：~/.workbuddy/skills/email-submission-daily/（详见 INSTALL.md）
• 自包含：所有路径基于脚本位置或环境变量，无机器相关绝对路径
• 依赖：Node（imap/exceljs/jszip/iconv-lite/mailparser）、Python（openpyxl/pillow/pillow_heif/python-docx/reportlab/pymupdf）
• 字体：PDF 默认 macOS 中文字体，跨平台需在 generate_summary_pdf_from_xlsx.py 改 FONT_PATH