Mail as Notes（Ob-Mail）—— Obsidian 邮件客户端插件（Foxmail 风格）

English: Mail as Notes is a desktop-only email client plugin for your vault. It sends and receives email via IMAP/SMTP and stores every message as a plain Markdown note with YAML frontmatter, so your mail becomes fully searchable, linkable and part of your knowledge base. It features multi-account setup with Keychain password storage, a classic Foxmail-style three-pane mail view (folder tree / message list / reading pane), a tab-based composer with drag-and-drop attachments, batch-paste recipients, contact autocomplete, drafts, reply/forward/spam actions, and safe scoped-CSS rendering of HTML emails.

在 Obsidian 中收发邮件的桌面端插件。核心理念：每一封邮件都是一条 Markdown 笔记——收取的邮件解析为带 frontmatter 的 Markdown 文件存入 Vault，天然融入 Obsidian 的双链、搜索与知识管理体系；同时提供 Foxmail 风格的三栏邮件视图与标签页式写信界面，兼顾传统邮件客户端的操作习惯。

• 插件 ID：ob-mail-client（插件名：Mail as Notes）
• 当前版本：1.4.2（变更见 RELEASE_NOTES.md）
• 界面视图：Foxmail 三栏视图（账户/文件夹树 + 邮件列表 + 阅读窗格）

功能清单

分类	功能
账户	多账户管理、IMAP/SMTP 服务器配置、SSL 与跳过证书验证、网络代理、连接测试按钮
安全	密码/授权码经 Obsidian Keychain 存储（passwordSecretId），兼容旧版明文回退
收取	手动收取、按周期自动收取（默认 5 分钟）、强制重新解析已下载邮件、增量去重
解析	HTML 邮件解析为 Markdown（可选保留原始样式渲染 / 转 Markdown / 格式化源码三种显示模式），附件落盘并以链接写入笔记
发送	标签页式写信视图、多账户选择、正文支持 Markdown、邮件签名、附件（选择器 + 拖拽）、发送后自动归档到「已发送」
收件人	联系人自动补全、批量粘贴（姓名<邮箱> 列表，逗号/分号/换行/制表符分隔，去重入联系人并反馈结果）、联系人选择弹窗
邮件操作	回复 / 回复全部 / 转发 / 作为附件转发 / 标记垃圾邮件 / 标记已读未读，回复与原邮件双向关联
草稿	保存草稿、从草稿恢复继续编辑、关闭标签页时三选一（保存草稿/不保存/取消）
视图	三栏视图预览即标记已读、未读角标、按主题/发件人/收件人过滤、双击在编辑器打开原始笔记、邮件头信息可折叠、列表/邮件头右键菜单（回复/转发等）
样式	作用域 CSS（cssclasses: email-note + 哈希作用域类），邮件样式不污染整个 Obsidian

系统要求

• 仅桌面端（isDesktopOnly: true，依赖 Node 网络库与文件系统）
• Obsidian ≥ 1.11.4（Keychain secretStorage API 要求）
• 邮件服务器需开启 IMAP/SMTP 服务（常见邮箱需使用授权码而非登录密码）

安装

方式一：从发布包安装

1. 下载发布包（见 RELEASE_NOTES.md 安装说明）；
2. 解压后将插件目录放入你的 Vault：{Vault}/.obsidian/plugins/ob-mail-client/，目录内应包含 main.js、manifest.json、styles.css；
3. 在 Obsidian「设置 → 第三方插件」中启用 Mail as Notes。

方式二：从源码构建

cd obsidian-mail
npm install
npm run build      # 生产构建，产物输出到 ./test_note/.obsidian/plugins/ob-mail-client/
npm run dev        # 开发模式（esbuild watch）

构建产物会自动复制到本仓库内置的 test_note 测试 Vault，可直接用 Obsidian 打开 test_note 进行验证。

快速开始

1. 「设置 → Mail as Notes」中点击 添加邮件账户，填写邮箱、IMAP/SMTP 服务器与端口、用户名，在「密码/授权码」处从 Keychain 选择或新建密钥；
2. 点击 测试 IMAP / 测试 SMTP 验证配置；
3. 执行命令 打开邮件客户端（Foxmail 风格）（或命令面板搜索「收取邮件」）收取第一批邮件；
4. 工具栏点击 写邮件 开始发送：支持联系人补全、批量粘贴收件人、拖拽文件添加附件；
5. 收取的邮件以 Markdown 笔记形式存放在 {存储路径}/{账户}/收件箱/YYYY-MM/ 下，可直接被 Obsidian 搜索、双链引用。

目录结构

obsidian-mail/
├── src/main.ts               # 插件全部源码（单文件，顶部有模块结构索引）
├── styles/foxmail-email.css  # 插件样式源文件（构建时复制为插件目录 styles.css）
├── styles/README-css-snippets.md  # 早期 CSS 片段文档（原根目录 readme，改名保留）
├── manifest.json             # Obsidian 插件清单
├── esbuild.config.js         # 构建脚本（含 CSS 复制插件）
├── version-bump.mjs          # 版本号递增脚本（仅递增 patch 位）
├── RELEASE_NOTES.md          # 发布说明与更新日志
├── docs/                     # 设计文档 / 使用手册 / 技术分析报告
├── test_note/                # 内置测试 Vault（含构建产物）
├── release/                  # 历史发布包与发布检查清单
└── .cowork-temp/             # 单元测试脚手架（test-parse.js 等）

仓库根目录（上一级）的 reaadme.md 是最初的需求规划与看板设计对话记录，保留作为设计演进的历史依据，详见 docs/design.md 的偏差说明。

文档导航

文档	内容
docs/design.md	设计文档：架构、数据结构、frontmatter 契约、存储布局、关键流程、安全设计
docs/USER_MANUAL.md	使用手册：账户配置、收发操作、拖拽附件、批量粘贴、常见问题
docs/ANALYSIS.md	技术分析报告：优势、取舍、问题与技术债务、改进路线
RELEASE_NOTES.md	版本发布说明与安装指南

命令一览

命令	说明
打开邮件客户端（Foxmail 风格）	激活三栏邮件视图
发送邮件	打开写信标签页
从草稿发送邮件	选取草稿继续编辑
收取邮件	手动收取所有账户新邮件
重新收取邮件（重新解析已下载邮件）	强制重新解析，用于修复解析问题
回复邮件 / 回复全部邮件 / 转发邮件 / 作为附件转发邮件 / 标记为垃圾邮件	针对当前活动邮件笔记的操作

发布流程（GitHub Actions 自动发布）

插件目录审查要求 main.js、manifest.json、styles.css 作为 Release 资产上传，不得提交到仓库（.gitignore 已排除 main.js 与 styles.css）。发布由 .github/workflows/release.yml 全自动完成：

1. 更新 manifest.json 的 version 与 RELEASE_NOTES.md，提交并推送；
2. 打 tag 并推送（tag 名 = 版本号，如 1.4.2）：git tag 1.4.2 && git push origin 1.4.2；
3. Action 自动执行：npm ci → npm run build（产物为仓库根 main.js 与 styles.css）→ 创建 GitHub Release（tag 作标题）并上传三个资产：main.js、manifest.json、styles.css（不含 zip 等其他文件）；
4. 插件目录对新 Release 自动重新审查。