Requirements
Binaries:
- -
himalaya - IMAP/SMTP CLI (brew install himalaya or cargo install himalaya) - INLINECODE3 - macOS only, built-in
Credentials:
- - App Password for Gmail (not regular password), stored in macOS Keychain
- Configure in INLINECODE4
Data Access
Read-only paths:
- -
~/Library/Mail/V*/MailData/Envelope Index - Apple Mail SQLite database (macOS only) - INLINECODE6 - attachment files (macOS only)
Scope
This skill:
- - ✅ Reads email via himalaya CLI or Apple Mail SQLite
- ✅ Sends email via himalaya (draft-review-send workflow)
- ✅ Searches and filters messages
- ❌ NEVER modifies credentials
- ❌ NEVER deletes emails without explicit confirmation
- ❌ NEVER auto-sends without user review
Quick Reference
| Topic | File |
|---|
| Apple Mail SQLite queries | INLINECODE7 |
| himalaya CLI patterns |
himalaya.md |
| Send/reply protocol |
sending.md |
Core Rules
1. Platform Detection
- - macOS with Apple Mail: Use SQLite queries (100x faster than AppleScript)
- Cross-platform: Use himalaya CLI for full IMAP/SMTP
- Never mix approaches in same task - commit to one to avoid state conflicts
2. Apple Mail SQLite
- - Query path: INLINECODE10
- Force sync first:
osascript -e 'tell app "Mail" to check for new mail' - SQLite reads stale data otherwise - Recent mail filter: INLINECODE12
- Join
messages→addresses on message_id for sender lookup
3. himalaya CLI
- - Always use:
--output json flag for programmatic parsing - List emails:
himalaya envelope list -o json (NOT message list) - Folder names are case-sensitive
- Run
himalaya folder list after server-side folder changes
4. Send Protocol
- - Draft-review-send workflow: Compose → show user full content → send after explicit OK
- Reply threading: Include
In-Reply-To and References headers or thread breaks - Some SMTP servers reject if From header doesn't match authenticated user
5. Credential Management
- - macOS Keychain: INLINECODE21
- Gmail/Google Workspace: Requires App Password with 2FA enabled
- OAuth: himalaya supports XOAUTH2 via token_cmd in config.toml
6. Thread Intelligence
- - Thread by
In-Reply-To chain, not subject matching - "Re:" prefix is unreliable
- Polling intervals: 15-30 min max; use
himalaya envelope watch for real-time
要求
二进制文件：
- - himalaya - IMAP/SMTP 命令行工具（brew install himalaya 或 cargo install himalaya）
- osascript - 仅限 macOS，系统内置
凭证：
- - Gmail 应用专用密码（非普通密码），存储在 macOS 钥匙串中
- 在 ~/.config/himalaya/config.toml 中配置
数据访问
只读路径：
- - ~/Library/Mail/V/MailData/Envelope Index - Apple Mail SQLite 数据库（仅限 macOS）
- ~/Library/Mail/V/MAILBOX/Messages/ - 附件文件（仅限 macOS）
范围
本技能：
- - ✅ 通过 himalaya 命令行工具或 Apple Mail SQLite 读取邮件
- ✅ 通过 himalaya 发送邮件（草稿-审核-发送工作流）
- ✅ 搜索和筛选消息
- ❌ 绝不修改凭证
- ❌ 未经明确确认绝不删除邮件
- ❌ 未经用户审核绝不自动发送
快速参考
| 主题 | 文件 |
|---|
| Apple Mail SQLite 查询 | apple-mail.md |
| himalaya 命令行模式 |
himalaya.md |
| 发送/回复协议 | sending.md |
核心规则
1. 平台检测
- - 使用 Apple Mail 的 macOS：使用 SQLite 查询（比 AppleScript 快 100 倍）
- 跨平台：使用 himalaya 命令行工具实现完整 IMAP/SMTP
- 同一任务中绝不混用方法 - 坚持一种方法以避免状态冲突
2. Apple Mail SQLite
- - 查询路径：~/Library/Mail/V*/MailData/Envelope\ Index
- 先强制同步：osascript -e tell app Mail to check for new mail - 否则 SQLite 读取的是过期数据
- 近期邮件筛选：WHERE datereceived > strftime(%s,now,-7 days)
- 通过 messageid 连接 messages→addresses 以查找发件人
3. himalaya 命令行工具
- - 始终使用：--output json 参数以便程序化解析
- 列出邮件：himalaya envelope list -o json（而非 message list）
- 文件夹名称区分大小写
- 服务器端文件夹变更后运行 himalaya folder list
4. 发送协议
- - 草稿-审核-发送工作流：撰写 → 向用户展示完整内容 → 明确确认后发送
- 回复线程：包含 In-Reply-To 和 References 标头或线程分隔
- 如果 From 标头与认证用户不匹配，某些 SMTP 服务器会拒绝
5. 凭证管理
- - macOS 钥匙串：security add-internet-password -s imap.gmail.com -a user@gmail.com -w app-password
- Gmail/Google Workspace：需要启用两步验证并生成应用专用密码
- OAuth：himalaya 通过 config.toml 中的 token_cmd 支持 XOAUTH2
6. 线程智能
- - 按 In-Reply-To 链而非主题匹配来组织线程
- Re: 前缀不可靠
- 轮询间隔：最多 15-30 分钟；实时监控使用 himalaya envelope watch
