mail-imap-sync

高性能IMAP邮件同步工具，支持多账号增量同步，按时间结构本地存储Markdown邮件，适合AI分析和邮件知识库构建。

Security Scan

The skill's code and instructions match its described purpose (IMAP -> local Markdown sync); no network exfiltration or unrelated permissions were found, but it stores credentials in a local config file and run.sh will pip-install dependencies — review those before use.

Purpose & Capability

Name/description (IMAP sync -> local markdown store) align with code: main.py uses imaplib to log into IMAP servers, fetch messages, parse them and write Markdown files in an emails/ tree. The included config.json, state.json and SKILL.md describe and match this behavior.

Instruction Scope

SKILL.md and run.sh tell the agent to run run.sh which installs two PyPI packages and runs main.py. The runtime reads config.json and state.json and writes files under emails/ and state.json. There are no instructions to read unrelated system files or send data to external endpoints beyond the IMAP servers. Important: credentials are provided in config.json (plaintext) according to the doc, so sensitive data is kept in a local file rather than a secret store.

Install Mechanism

No formal install spec in registry, but run.sh executes 'pip install python-dateutil html2text' at runtime. Installing packages from PyPI is normal for Python scripts but will modify the runtime environment — consider running in a virtualenv/container and inspect the packages before installation.

Credentials

The skill does not request environment variables or platform credentials, but it relies on config.json containing account credentials (pass field). Storing IMAP passwords in plaintext in config.json is sensitive and not explicitly addressed in SKILL.md. There is no integration with secret storage or an option to supply credentials via environment variables.

Persistence & Privilege

Flags show normal privileges (always:false). The skill does not request permanent platform injection, does not modify other skills, and only writes its own state.json and emails/ files.

Assessment

This skill appears to do what it claims (download IMAP mail and save as Markdown), but take these precautions before installing or running it: - Inspect and edit config.json: the example uses a 'pass' field stored in plaintext. Replace with an application-specific password and remove credentials from bundled files before use. Prefer supplying credentials via a secure mechanism (environment variables, OS keyring, or a secrets manager) rather than committing them to disk. - Run in an isolated environment (virtualenv, container, or VM) because run.sh will pip-install packages into the environment. - Review the included code (main.py) yourself — it handles IMAP login and file writes, and there's no remote exfiltration, but you should confirm it meets your policies. - Backup or sandbox: running against an important account is risky until you validate behavior; test with a disposable account first. - Note the small inconsistencies: run.sh suppresses pip output which can hide install problems, and the code declares a LOCAL_TZ of Asia/Taipei while normalize_email_date uses Asia/Shanghai — verify timezone handling if that matters. If you need help converting credential handling to environment variables or a safer secret store, or want a quick checklist to sandbox the skill, I can provide one.

📬 Mail IMAP Sync Skill

🧠 功能概述

本技能用于：

• 📥 从 IMAP 邮箱同步邮件（支持 Gmail / 企业邮箱）
• ⚡ 高性能拉取（服务器端过滤，不扫全量）
• 🔁 自动增量（基于 UID）
• 🧱 本地结构化存储（Markdown + 时间分层）
• 🧠 为 AI 提供可读邮件数据源

---

🚀 支持的同步模式

🥇 1. init（纯增量模式）

"mode": "init"

• 第一次运行：不拉历史邮件
• 后续：只同步新邮件

👉 适合长期运行系统

---

🥈 2. recent（推荐）

"mode": "recent",
"recent_days": 7

• 第一次：拉取最近 N 天邮件
• 后续：自动增量

👉 推荐用于 AI 分析 / 日报

---

🥉 3. since（指定日期）

"mode": "since",
"since": "2026-01-01"

• 第一次：拉取指定日期之后邮件
• 后续：增量同步

👉 用于历史导入

---

📁 存储结构

邮件以 Markdown 格式存储：

emails/
  {account}/
    YYYY/
      MM/
        DD/
          UID_MessageID_标题.md

---

🧾 邮件结构（标准化）

每封邮件包含：

# Subject

From: xxx
Date(raw): 原始时间
Date(local): 本地时间（Asia/ShangHai）
Date(ISO): ISO标准格式
Timestamp: Unix时间戳

UID: xxx
Message-ID: xxx
Account: xxx

---

正文内容

---

⏱ 时间处理（核心特性）

• 自动解析各种邮件时间格式

• 统一转换为：

  • Asia/ShangHai 时区
  • ISO标准格式
  • 时间戳（用于排序/分析）

👉 保证 AI 可稳定理解时间

---

⚡ 性能优化

本技能使用：

• IMAP SEARCH SINCE（服务器过滤）
• UID 增量同步
• 避免扫描整个邮箱

👉 支持万级邮件秒级同步

---

🔁 去重机制

• UID 去重
• Message-ID 去重
• 文件存在即跳过

---

🧱 稳定性保障

• state.json 原子写入（防损坏）
• Ctrl+C 不会丢状态
• 自动检测异常状态并修复
• 支持断点恢复

---

⚙️ 配置方式（config.json）

{
  "accounts": [
    {
      "name": "bettermsao",
      "imap_host": "imap.gmail.com",
      "user": "[e-mail]",
      "pass": "应用专用密码",
      "mode": "recent",
      "recent_days": 7
    }
  ]
}

---

▶️ 运行方式

./run.sh

---

📤 输出说明

返回：

{
  "synced_emails": [
    "emails/.../xxx.md"
  ]
}

---

🧩 适用场景

• 📊 邮件数据分析
• 🤖 AI 邮件总结（日报 / 周报）
• 🚨 重要邮件监控
• 🧠 本地 LLM 数据输入

---

🔮 可扩展方向

• 邮件自动总结（LLM）
• 分类（订单 / 客户 / 系统）
• 向量化（语义搜索）
• 通知推送（微信 / Telegram）
• 多邮箱聚合分析

---

⚠️ 注意事项

• Gmail 需开启 IMAP 并使用应用专用密码
• 企业邮箱可能限制 IMAP 频率
• 初次运行建议使用 recent 模式

---

🏁 总结

本技能将邮件系统转化为：

👉 可结构化存储 👉 可被 AI 理解 👉 可持续增量更新