claude-code-remote-remake/docs/EMAIL_GUIDE.md

# TaskPing 邮件功能使用指南

## 🌟 功能概述

TaskPing 现在支持邮件通知和远程命令执行功能，让您可以：

1. **📧 接收邮件通知** - 当 Claude Code 任务完成时，自动发送邮件通知
2. **🔄 远程命令执行** - 通过回复邮件来远程执行 Claude Code 命令
3. **🏠 真正的远程工作** - 即使不在电脑前，也能继续与 Claude Code 对话

## 🚀 快速开始

### 步骤 1: 配置邮件设置

```bash
# 启动配置管理器
node taskping.js config

# 选择 "3. 通知渠道"
# 然后选择 "2. 邮件通知"
```

### 步骤 2: 输入邮箱配置

以 Gmail 为例：

```
SMTP 主机: smtp.gmail.com
SMTP 端口: 587  
使用 SSL/TLS: n (使用 STARTTLS)
SMTP 用户名: your-email@gmail.com
SMTP 密码: your-app-password  # 需要使用应用密码

IMAP 主机: imap.gmail.com
IMAP 端口: 993
IMAP 使用 SSL: y

收件人邮箱: your-email@gmail.com
发件人显示名: TaskPing <your-email@gmail.com>
```

### 步骤 3: 测试邮件发送

配置完成后，选择测试邮件发送功能，您应该会收到一封测试邮件。

### 步骤 4: 启动命令中继服务

```bash
# 启动邮件命令中继服务
node taskping.js relay start
```

## 📋 详细配置指南

### Gmail 配置

1. **启用两步验证**
   - 登录 Google 账户
   - 进入"安全"设置
   - 启用两步验证

2. **生成应用密码**
   - 在 Google 账户安全设置中
   - 选择"应用密码"
   - 选择"邮件"和您的设备
   - 复制生成的 16 位密码

3. **启用 IMAP**
   - 登录 Gmail
   - 进入设置 → 转发和POP/IMAP
   - 启用 IMAP 访问

### Outlook/Hotmail 配置

```
SMTP 主机: smtp.live.com
SMTP 端口: 587
IMAP 主机: imap-mail.outlook.com  
IMAP 端口: 993
```

### 其他邮箱提供商

| 提供商 | SMTP 主机 | SMTP 端口 | IMAP 主机 | IMAP 端口 |
|--------|-----------|-----------|-----------|-----------|
| QQ邮箱 | smtp.qq.com | 587 | imap.qq.com | 993 |
| 163邮箱 | smtp.163.com | 587 | imap.163.com | 993 |
| 126邮箱 | smtp.126.com | 587 | imap.126.com | 993 |

## 🔄 使用流程

### 1. 正常工作流程

```
1. 启动 Claude Code
2. 执行任务 (如: "帮我重构这个组件")
3. 📧 收到邮件通知: "任务完成"
4. 💬 回复邮件: "请添加单元测试"
5. ⚡ 命令自动在 Claude Code 中执行
```

### 2. 邮件通知示例

当 Claude Code 完成任务时，您会收到如下邮件：

```
主题: [TaskPing] Claude Code 任务完成 - MyProject

🎉 Claude Code 任务完成

项目: MyProject
时间: 2025-07-12 19:45:30
状态: 任务完成

消息: 任务已完成，Claude正在等待下一步指令

💡 如何继续对话
要继续与 Claude Code 对话，请直接回复此邮件，在邮件正文中输入您的指令。

示例回复:
• "请继续优化代码"
• "生成单元测试"
• "解释这个函数的作用"

会话ID: 123e4567-e89b-12d3-a456-426614174000
🔒 安全提示: 请勿转发此邮件，会话将在24小时后自动过期
```

### 3. 回复邮件执行命令

直接回复邮件，在正文中输入要执行的命令：

```
请添加错误处理和日志记录功能
```

系统会自动：
1. 识别邮件回复
2. 提取命令内容  
3. 验证会话有效性
4. 在 Claude Code 中执行命令

## 🛠️ 管理命令

### 查看中继服务状态

```bash
node taskping.js relay status
```

输出示例：
```
📊 命令中继服务状态

✅ 邮件配置已启用
📧 SMTP: smtp.gmail.com:587
📥 IMAP: imap.gmail.com:993
📬 收件人: your-email@gmail.com

📋 命令队列: 3 个命令

最近的命令:
  ✅ abc123: 请添加错误处理功能...
  ⏳ def456: 生成单元测试...  
  ⏸️ ghi789: 优化性能...
```

### 清理命令历史

```bash
node taskping.js relay cleanup
```

### 停止中继服务

在运行中继服务的终端中按 `Ctrl+C`

## 🔒 安全特性

### 会话管理
- **唯一会话ID**: 每个通知邮件包含唯一的 UUID
- **24小时过期**: 会话自动过期，防止滥用
- **命令限制**: 每个会话最多 10 个命令

### 内容安全
- **邮件验证**: 验证回复邮件来源
- **命令过滤**: 过滤危险命令
- **长度限制**: 命令长度限制在 1000 字符内

### 危险命令黑名单
系统会自动拒绝以下类型的命令：
- `rm -rf` (删除文件)
- `sudo` (提权操作)
- `curl | sh` (执行远程脚本)
- `eval` / `exec` (代码执行)

## 🚨 故障排除

### 无法发送邮件

**问题**: 邮件发送失败
**解决方案**:
1. 检查 SMTP 配置是否正确
2. 确认使用应用密码而非普通密码
3. 检查网络连接
4. 查看防火墙设置

```bash
# 测试邮件发送
node taskping.js config
# 选择通知渠道 → 邮件通知 → 测试
```

### 无法接收回复

**问题**: 回复邮件后命令不执行
**解决方案**:
1. 确认中继服务正在运行
2. 检查 IMAP 配置
3. 确认回复的是 TaskPing 邮件
4. 检查命令是否被安全过滤器拦截

```bash
# 检查中继服务状态
node taskping.js relay status

# 重启中继服务
node taskping.js relay start
```

### 会话过期

**问题**: 提示会话过期
**解决方案**:
- 会话在24小时后自动过期
- 需要等待新的任务完成通知
- 或手动发送测试通知

### Claude Code 进程检测失败

**问题**: 无法找到 Claude Code 进程
**解决方案**:
1. 确保 Claude Code 正在运行
2. 检查进程名称是否正确
3. 目前支持自动化输入的平台：macOS

## 📱 高级用法

### 多项目管理

不同项目的通知邮件会包含项目名称，方便区分：

```
[TaskPing] Claude Code 任务完成 - Frontend-Project
[TaskPing] Claude Code 任务完成 - Backend-API  
[TaskPing] Claude Code 任务完成 - Mobile-App
```

### 命令模板

常用命令模板：

```bash
# 代码优化
"请优化性能并添加注释"

# 测试生成  
"为这个函数生成单元测试"

# 文档生成
"生成 API 文档"

# 代码审查
"审查代码并指出潜在问题"

# 重构建议
"建议如何重构这段代码"
```

### 批量操作

可以在一封回复邮件中包含多个步骤：

```
请按以下步骤处理：
1. 优化函数性能
2. 添加错误处理
3. 生成单元测试
4. 更新文档
```

## 🎯 最佳实践

### 1. 安全建议
- 不要在邮件中包含敏感信息
- 定期更换应用密码
- 不要转发 TaskPing 通知邮件
- 及时清理过期会话

### 2. 命令编写
- 使用清晰、具体的指令
- 避免过于复杂的命令
- 一次专注一个任务
- 使用自然语言，无需特殊格式

### 3. 工作流程
- 启动工作时开启中继服务
- 结束工作时关闭中继服务
- 定期查看中继状态
- 及时清理命令历史

## 🆘 常见问题

**Q: 邮件功能会影响现有的桌面通知吗？**
A: 不会。邮件通知和桌面通知是独立的，可以同时启用。

**Q: 可以配置多个邮箱吗？**
A: 目前支持一个邮箱配置，但可以发送给多个收件人（在配置中用逗号分隔）。

**Q: 支持哪些邮箱提供商？**
A: 支持所有标准的 SMTP/IMAP 邮箱服务，包括 Gmail、Outlook、QQ、163 等。

**Q: 命令执行失败怎么办？**
A: 系统会自动重试 3 次，如果仍然失败，会在状态中显示错误信息。

**Q: 如何确保数据安全？**
A: 所有邮件配置存储在本地，使用应用密码而非主密码，会话自动过期。

## 🎉 开始使用

现在您已经了解了 TaskPing 邮件功能的所有细节，可以开始配置和使用了：

```bash
# 1. 配置邮箱
node taskping.js config

# 2. 测试通知
node taskping.js test

# 3. 启动中继服务
node taskping.js relay start

# 4. 开始使用 Claude Code，享受远程工作的便利！
```

享受您的远程 AI 编程体验！🚀