lgwanai/mail-skill

Latest recorded source activity: September 9, 2026 at 16:35

SkillsMP catalog refreshed: November 12, 2026 at 12:52

skills collected: 1

GitHub stars: 29
GitHub forks: 2

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/lgwanai/mail-skill.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# Mail Skill 面向 Agent 平台的邮件 Skill。脚本负责收发、归档、检索、状态同步与附件提取；当前 Agent 负责理解、总结、分类判断和回复撰写。外部大模型、视觉 API 和云端 embedding 的调用及配置已移除。本地 OCR 复用 `~/workspace/llm-wiki-skill` 的 CLI。 ## 安装与首次检查核心支持 Python 3.10+、Linux/macOS、SQLite 3.34+ FTS5。Windows 可使用 Linux runner。当前本地 OCR/MLX 链路在 Apple Silicon 验证，其他平台需配置兼容运行时；缺少 OCR 不影响核心收发和归档。 ```bash python -m venv .venv source .venv/bin/activate python -m pip install --require-hashes -r locks/core.txt # PDF/Office/图片解析与 OS keychain 适配器： python -m pip install --require-hashes -r locks/runtime.txt python scripts/mail_cli.py doctor python scripts/mail_cli.py capabilities ``` 复制 `example.config.txt`，配置邮箱服务器和凭证引用。使用 `MAIL_CONFIG_FILE=/absolute/path/config.txt` 固定配置路径；相对存储路径以配置文件目录解析。默认运行数据在 `~/.local/share/mail-skill`，不进入源码发布包。 ```bash python scripts/mail_cli.py auto-configure user@example.com --password-ref keyring:mail-skill/user@example.com ``` 命令只返回服务器配置和凭证引用。凭证由平台通过 OS keychain、受保护文件或环境注入，不在对话和命令行中传密码。也支持 OAuth/XOAUTH2 与带锁的 token 刷新，详见 [企业运行说明](references/enterprise-operations.md)。 ## 常用工作流 ```bash # 异步收取与状态检查 python scripts/mail_cli.py fetch --account user@example.com --folder ALL --days 7 python scripts/mail_cli.py task-status <task_id> # 邮件及附件全文、中文子串检索 python scripts/mail_cli.py search-evidence '付款条件' --account user@example.com python scripts/mail_cli.py evidence-read <attachment_id> --account user@example.com --page 3 # 无条件归档全部文件夹、全部时间、全部附件 python scripts/mail_cli.py archive --account user@example.com # 也可按时间、文件夹、发件人、关键词组合筛选，见归档文档 # 异步提取附件；当前 Agent 读取证据并解读 python scripts/mail_cli.py parse-attachments --all --account user@example.com # 为当前 Agent 准备完整回复上下文 python scripts/mail_cli.py ai-reply <message_id> --account user@example.com --with-thread # 先形成完整待发草稿和附件清单 python scripts/mail_cli.py send --account user@example.com --to recipient@example.com \ --subject '项目进展' --body-file /draft/body.txt --attach /draft/report.pdf \ --idempotency-key workflow-123 --prepare-only ``` 完成用户已授权的发送时，以同样参数去掉 `--prepare-only`。托管平台还需提供绑定 payload_hash 的签名授权。SMTP 接受、部分拒收、发送结果未知分别报告；unknown 不自动重发。同一幂等键不会再次提交，任何必需附件缺失都会终止。 CLI 返回单个 [v1 JSON envelope](schemas/tool-response.schema.json)，任务 ID 只能读取 `data.task_id`；顶层 `request_id` 只是本次 CLI 调用 ID，不能用于查询或恢复任务。启动成功不是任务完成。大输出返回 `artifact_available` 及文件引用，使用 `artifact-read` 分段读取。退出码为 0（完成/接收/交给 Agent）、2（错误）、3（部分/未知/制品待处理）、130（取消）。 ## 大规模离线归档新归档使用简洁的离线 HTML 阅读页，邮箱地址点击复制，附件直接下载，完整邮件头和备用正文可展开。回复或转发邮件会通过常见客户端标记和纯文本分隔符，把本次正文与引用的历史邮件分区展示，并保留未分区的完整原始正文用于核对。默认不传筛选条件可归档全部邮件并完整下载附件；也支持按时间、文件夹、发件人、关键词组合筛选后归档。归档实现采用企业级路径： - 归档后保留原始 EML、全部 MIME 组件、附件、邮件头、正文所有可见文本与可用的 `text/plain`/`text/html` 备选体，不进行内容压缩或降级处理； - 采用两级哈希目录与每封独立目录，邮件正文统一渲染为离线 HTML，附件统一落在 `attachments/` 子目录，HTML 中所有资源使用相对路径，可离线双击打开； - IMAP 断线会重新登录、重新选择只读文件夹并重试当前 UID；重连耗尽后任务立即以可恢复状态停止，避免把后续未尝试邮件批量计为失败； - 归档目录使用 `catalog.sqlite3` 持久化元数据（按需增量）和脏页标记，采用 200 条/页的目录分页，首次扫描后续写入仅增量更新页面； - 索引与查询基于全文索引（FTS5）与三元组检索，结合游标分页与分页锚点，支持十万级库的持续检索； - SQLite 使用 WAL 与轻量更新条件触发，避免无意义重建索引；消息元数据更新优先走轻量字段和批量游标扫描，减少长事务阻塞； - 存储层对每封邮件都做 SHA256 校验，失败写入落本地 `.failures` JSONL 并在列表返回中保留最近错误摘要与完整日志路径，失败不影响已完成邮件的持久化。已通过 15 万封合成邮件验证：15,000 条预期检索命中全部找回，单页 P95 约 94 ms。实测范围、内存、存储与部署边界见 [性能记录](references/archive-performance.md)；这不包含真实服务器下载或 OCR 吞吐量。 ## 原件和附件保留每封归档保留原始 EML、全部 MIME 部分及 SHA256 清单。正文统一展示为 HTML，附件集中在附件目录，HTML 使用相对链接，可离线双击打开。重复文件名、无文件名附件、内嵌图片和嵌套邮件均保留。完整文件校验后才标记归档；归档邮件继续参与本地检索，后续收取和状态同步排除其服务器身份。归档不会删除或移动服务器邮件。提取和 OCR 是原件的派生证据，不能替代原件。PDF 原生文字、页图、Office XML/备注/嵌入内容、OCR Markdown 和核验版本保留。分页/附件预算超限、加密或不支持的文件明确列为待处理，不以非空文本冒充完整。当前 Agent 核验后可写入新转录版本，保留旧版本。解析在有超时、内存、页数、像素及展开大小限制的子进程运行。PDF OCR 按批次持久化检查点，重试复用已完成页批次；主机级 OCR 锁限制模型并发。核心工作不调用外部模型。可选本地向量检索依赖单列于 `requirements-vector.txt`，普通检索和保存不加载它。 ## 企业部署与恢复 - 稳定 tenant/account 身份、归属标记与目录碰撞检查；版本化数据库迁移及升级前快照。 - 邮件服务器副本、RFC Message-ID、原件哈希、附件和提取版本分别保存；重复同步不清除核验文字。 - 可监督任务：队列、心跳、租约、进度、取消、恢复及防重复执行。平台会杀掉整任务容器时，使用 `MAIL_JOB_EXECUTION=queue`，由独立服务托管 `python scripts/mail_worker.py`。 - 托管模式校验平台签名的主体/账户/租户/路径/能力范围；发送授权绑定草稿和附件哈希；元数据审计与哈希链校验。 - 异步 `backup/restore/verify/repair/account-migrate`；SQLite 在线备份、原件校验、可移植恢复、数据库及检索重建。`cache-gc` 默认预览，只清可再生缓存。共享部署仍需平台的 IAM、受保护 Secret Broker、OS/容器租户隔离和持久 worker。Python 权限检查不能限制同一 OS 用户的任意 Shell 读取；本项目不替代平台隔离。保留离线 HTML 使用体验，静态加密交给平台磁盘或备份层。 ## 文档 | 内容 | 入口 | |---|---| | Agent 触发和完整命令说明 | [SKILL.md](SKILL.md) | | 当前 Agent 理解、总结、回复 | [Agent 工作流](references/agent-workflow.md) | | 条件归档、原件保留、相对 HTML | [归档](references/archive.md) | | OCR、附件证据、核验回写 | [附件解析](references/attachment-parsing.md) | | 身份、权限、凭证、任务、恢复、协议 | [企业运行](references/enterprise-operations.md) | | 企业优化清单逐项落实与验证 | [实施记录](references/enterprise-implementation.md) | ## 验证和发布 ```bash python -m pip install --require-hashes -r locks/dev.txt python -m pytest python -m ruff check scripts tests python scripts/benchmark_search.py --records 10000 python -m pip_audit -r locks/runtime.txt --disable-pip --no-deps bash build.sh ``` CI 配置覆盖 Ubuntu Python 3.10/3.12 和 macOS Python 3.12，进行测试、源码检查、基准、打包和依赖扫描。测试默认禁用外部网络，不访问真实邮箱或调用外部推理。发布 ZIP/Skill 采用源码允许清单和内容哈希，包含分类规则、Schema 和依赖锁文件，排除邮件、数据库、任务、凭证和日志。

Loading the repository README…

Skills in this repository

Office Clerks, General

1 occupation category · 100% classified

skill

occupation

description

updated

mail-skill

Office Clerks, General

Comprehensive email management skill for AI agents. Fetches, searches, reads, sends, and summarizes emails via IMAP/SMTP. Features include semantic search with optional vector embeddings, current-Agent replies, email classification, thread tracking,…

2026-09-09

Showing 1 of 1 collected skill.