HEY PWA Mailto Handler - Manifest Modifier

README.md

HEY PWA Mailto Handler

让 HEY PWA 支持处理系统 mailto 链接，点击邮件地址自动打开 HEY 撰写窗口并填入收件人。

概述

本项目通过 Surge 代理规则，为 HEY PWA 添加 mailto: 协议处理能力，实现点击邮件链接自动唤起 HEY 撰写界面。

核心功能：

• 注册 PWA 为系统 mailto 协议处理程序
• 自动解析并填充收件人地址
• 无缝集成系统邮件工作流

技术方案：

• 修改 Web App Manifest，添加 protocol_handlers
• 使用 URL Rewrite 转换请求参数格式
• 通过 MITM 拦截和修改 HTTPS 响应

项目地址

🔗 GitHub Gist: https://gist.github.com/dismory/3f052ec4c5274e4ec79d3c2cbdf11f2c

使用说明

Note

使用说明和配置基于 Surge 版本 Version 6.4.1 (9550)。

前置要求 ⚠️

Important

必须启用 MITM（中间人拦截）

模块需要修改 HTTPS 响应内容，必须先配置 MITM：

1. 生成并安装证书

   Surge → 首页 → MITM → 配置根证书 → 生成新的 CA 证书 → 安装证书
   

2. 启用 MITM

   Surge → 首页 → MITM → MITM 开关 → 打开
   

没有 MITM，所有规则都不会生效。

---

1. 安装模块

方式 A：本地安装

1. 将 hey-manifest.js 保存到 Surge 配置目录
2. 在脚本配置中更新 script-path 为本地路径
3. 将模块配置保存为 HEY-Mailto.sgmodule
4. 将 HEY-Mailto.sgmodule 上传到指定远端并获取 URL
5. Surge → 模块 → 从 URL 安装模块 → 输入模块 URL

方式 B：从 URL 安装

Surge → 模块 → 从 URL 安装模块 → 输入模块 URL

---

2. 安装/重装 HEY PWA

重要：确保 Surge 模块和 MITM 已启用

1. ✅ 启用模块
2. ✅ 确认 MITM 已开启
3. 访问 https://app.hey.com
4. 卸载旧的 HEY PWA（如果已安装）
5. 清除浏览器缓存（Cmd + Shift + Delete）
6. 强制刷新页面（Cmd + Shift + R）
7. 点击地址栏右侧安装图标，重新安装 PWA
8. 验证： F12 → Application → Manifest，检查是否有 protocol_handlers 字段

---

3. 设置系统默认邮件程序

macOS

系统设置 → 桌面与程序坞 → 默认电子邮件阅读程序 → 选择 HEY

Windows

设置 → 应用 → 默认应用 → 邮件 → 选择 HEY

Chrome（备选）

chrome://settings/handlers → 协议处理程序 → 将 HEY 设为 mailto 默认处理

---

4. 测试

点击任意 mailto:xxx@example.com 链接，应该：

• ✅ 自动打开 HEY PWA（独立窗口）
• ✅ 进入撰写页面（/messages/new）
• ✅ 自动填入收件人地址

测试链接： 在浏览器地址栏输入 mailto:test@example.com

---

5. 后续维护

PWA 安装成功后的规则使用：

规则	是否保持启用	说明
MITM	✅ 必须	URL Rewrite 依赖 MITM 拦截 HTTPS
URL Rewrite	✅ 必须	每次点击 mailto 都需要重写 URL
Header Rewrite	⚠️ 可选	仅重装 PWA 时需要
Script (hey-manifest)	⚠️ 可选	仅重装 PWA 时需要

性能优化建议： PWA 安装后可停用 Script 和 Header Rewrite 规则，但必须保留 URL Rewrite 和 MITM。

---

工作原理

用户点击 mailto:support@example.com
        ↓
系统调用 PWA（通过 manifest protocol_handlers）
        ↓
PWA 请求: /messages/new?to=mailto:support@example.com
        ↓
📡 Surge MITM 拦截 HTTPS 请求
        ↓
🔄 Surge URL Rewrite 修改 URL
        ↓
实际请求: /messages/new?to=support@example.com
        ↓
✅ HEY 识别并填入邮箱地址

---

故障排查

❌ 规则完全不生效

现象： 点击 mailto 没反应，Surge Dashboard 无任何日志

原因： MITM 未启用

解决：

1. 检查 Surge 首页 MITM 开关是否打开
2. 检查钥匙串中 Surge 证书是否为"始终信任"
3. 确认配置中有 hostname = app.hey.com

---

❌ PWA 没有响应 mailto 链接

现象： 点击 mailto 打开了其他邮件程序或没反应

解决：

• 检查系统默认邮件程序是否设置为 HEY
• 重新安装 PWA（确保模块已启用）
• F12 → Application → Manifest，确认有 protocol_handlers 字段

---

❌ 邮箱地址没有填入

现象： HEY 打开了但收件人为空，或显示 mailto:xxx

检查：

1. Surge Dashboard 搜索 messages/new 请求
2. 查看 Events 是否有 [Rewrite] Matched URL rewrite rule
3. 确认 URL Rewrite 使用 header 模式（不是 302/307）

解决：

# 确保配置正确
^https://app\.hey\.com/messages/new\?to=mailto%3A(.+)$ https://app.hey.com/messages/new?to=$1 header

---

❌ Manifest 修改不生效

现象： F12 看不到 protocol_handlers 字段

检查：

1. Surge 日志是否显示 ✅ Manifest 修改完成
2. 是否返回 304 缓存响应（日志会显示 ⚠️ 304）
3. 脚本文件路径是否正确

解决：

# 1. 强制清除缓存
Chrome → Cmd + Shift + Delete → 缓存的图片和文件

# 2. 检查 Header Rewrite 规则
应该有 header-del If-None-Match 规则

# 3. 卸载 PWA 重新安装
确保 Surge 模块已启用且 MITM 已开启

---

兼容性

平台/软件	支持情况	说明
Surge Mac 6.4+	✅ 完全支持	推荐版本
Surge iOS	未测试	iOS 不支持 PWA 的 protocol_handlers？
HEY (app.hey.com)	✅ 完全支持	已测试
Chrome PWA	✅ 完全支持	已测试
Safari	⚠️ 有限支持	Safari 的 PWA 支持有限

---

安全说明

Caution

MITM 风险： 启用 MITM 后 Surge 可以解密所有 HTTPS 流量。

降低风险措施：

• ✅ 仅针对 app.hey.com 域名（已限制）
• ✅ 使用受信任的规则和脚本
• ✅ 定期检查 Surge 配置
• ✅ 不使用来源不明的模块

---

技术参考

Web 标准与规范

• Web App Manifest - PWA 清单文件标准
• URL Protocol Handler Registration - Protocol Handlers 规范
• Launch Handler API - PWA 启动处理 API
• Content Security Policy (CSP) - 内容安全策略

Surge 文档

• Surge 用户手册 - 完整配置参考
• Module - Module
• URL Rewrite - URL 重写规则
• HTTP Scripting - HTTP 脚本开发
• MITM 解密 - 中间人拦截配置

相关工具

• HEY - 邮件服务
• Surge - 网络调试工具
• PWA Builder - PWA 开发资源

---

许可证

MIT License

---

贡献： 欢迎留下你的评论

支持项目： 如果对你有帮助，请给个 ⭐ Star

hey-manifest.js

// HEY PWA Mailto Handler - Manifest Modifier
// 为 HEY 添加 mailto protocol handler 支持

console.log("=== HEY Manifest Modifier ===");

// 处理 304 缓存响应
if ($response.status === 304 || !$response.body) {
  console.log("⚠️ 304 或空响应体，跳过修改");
  $done({});
} else {
  try {
    let manifest = JSON.parse($response.body);
    
    // 添加 mailto protocol handler
    manifest.protocol_handlers = [
      {
        protocol: "mailto",
        url: "/messages/new?to=%s"
      }
    ];
    
    // 添加 launch handler，确保每次打开都导航到新 URL
    manifest.launch_handler = {
      client_mode: "navigate-new"
    };
    
    console.log("✅ Manifest 修改完成");
    console.log("   - 已添加 mailto protocol handler");
    console.log("   - 已添加 navigate-new launch handler");
    
    $done({ body: JSON.stringify(manifest) });
  } catch (e) {
    console.log("❌ JSON 解析失败:", e.message);
    $done({});
  }
}

HEY-PWA-Mailto.sgmodule

#!name=HEY PWA Mailto Handler
#!desc=让 HEY PWA 支持 mailto 协议处理
#!author=dismory
#!homepage=https://gist.github.com/dismory/3f052ec4c5274e4ec79d3c2cbdf11f2c
#!icon=https://app.hey.com/favicon.ico

[URL Rewrite]
# 移除 mailto: 前缀，转换 to 参数
^https://app\.hey\.com/messages/new\?to=mailto%3A(.+)$ https://app.hey.com/messages/new?to=$1 header

[Header Rewrite]
# 避免 manifest.json 缓存，确保修改生效
^https://app\.hey\.com/manifest\.json header-del If-None-Match
^https://app\.hey\.com/manifest\.json header-del If-Modified-Since
^https://app\.hey\.com/manifest\.json header-del Accept-Encoding

[Script]
# 修改 manifest.json，添加 protocol_handlers
hey-manifest = type=http-response, pattern=^https://app\.hey\.com/manifest\.json, requires-body=1, max-size=16384, script-path=https://gist.githubusercontent.com/dismory/3f052ec4c5274e4ec79d3c2cbdf11f2c/raw/f4b0afce56ca0cae21c2d6c1f09de07b9b2399ec/hey-manifest.js

[MITM]
hostname = %APPEND% app.hey.com