5.8 KiB
5.8 KiB
TaskPing 邮件回复功能使用指南
概述
TaskPing 的邮件回复功能允许您通过回复邮件的方式向 Claude Code CLI 发送命令。当您在移动设备或其他电脑上收到 TaskPing 的任务提醒邮件时，可以直接回复邮件来控制 Claude Code 继续执行任务。
工作原理
- 发送提醒: Claude Code 在任务暂停时发送包含会话 Token 的提醒邮件
- 邮件监听: PTY Relay 服务持续监听您的收件箱
- 命令提取: 从回复邮件中提取命令内容
- 命令注入: 通过 node-pty 将命令注入到对应的 Claude Code 会话
快速开始
1. 配置邮件账号
复制环境配置文件：
cp .env.example .env
编辑 .env 文件，填入您的邮件配置：
# Gmail 示例
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your-email@gmail.com
IMAP_PASS=your-app-password # 使用应用专用密码
# 安全设置
ALLOWED_SENDERS=your-email@gmail.com,trusted@company.com
2. 启动 PTY Relay 服务
npm run relay:pty
# 或者
./start-relay-pty.js
3. 测试邮件解析
运行测试工具验证配置：
npm run relay:test
使用方法
邮件格式要求
主题格式
邮件主题必须包含 TaskPing Token，支持以下格式：
[TaskPing #TOKEN]- 推荐格式[TaskPing TOKEN]TaskPing: TOKEN
例如：
Re: [TaskPing #ABC123] 任务等待您的指示回复: TaskPing: XYZ789
命令格式
支持三种命令输入方式：
-
直接输入（最简单）
继续执行 -
CMD 前缀（明确标识）
CMD: npm run build -
代码块（复杂命令）
``` git add . git commit -m "Update features" git push ```
示例场景
场景 1: 简单确认
收到邮件：
主题: [TaskPing #TASK001] 是否继续部署到生产环境？
回复：
yes
场景 2: 执行具体命令
收到邮件：
主题: [TaskPing #BUILD123] 构建失败，请输入修复命令
回复：
CMD: npm install missing-package
场景 3: 多行命令
收到邮件：
主题: [TaskPing #DEPLOY456] 准备部署，请确认步骤
回复：
执行以下命令：
```
npm run test
npm run build
npm run deploy
```
高级配置
会话管理
会话映射文件 session-map.json 结构：
{
"TOKEN123": {
"type": "pty",
"createdAt": 1234567890,
"expiresAt": 1234654290,
"cwd": "/path/to/project",
"description": "构建项目 X"
}
}
环境变量说明
| 变量名 | 说明 | 默认值 |
|---|---|---|
IMAP_HOST |
IMAP 服务器地址 | 必需 |
IMAP_PORT |
IMAP 端口 | 993 |
IMAP_SECURE |
使用 SSL/TLS | true |
IMAP_USER |
邮箱账号 | 必需 |
IMAP_PASS |
邮箱密码 | 必需 |
ALLOWED_SENDERS |
允许的发件人列表 | 空（接受所有） |
SESSION_MAP_PATH |
会话映射文件路径 | ./src/data/session-map.json |
CLAUDE_CLI_PATH |
Claude CLI 路径 | claude |
LOG_LEVEL |
日志级别 | info |
PTY_OUTPUT_LOG |
记录 PTY 输出 | false |
邮件服务器配置示例
Gmail
- 启用 IMAP: 设置 → 转发和 POP/IMAP → 启用 IMAP
- 生成应用专用密码: 账号设置 → 安全 → 应用专用密码
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
Outlook/Office 365
IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
QQ 邮箱
IMAP_HOST=imap.qq.com
IMAP_PORT=993
IMAP_SECURE=true
安全注意事项
- 发件人验证: 始终配置
ALLOWED_SENDERS以限制谁可以发送命令 - 命令过滤: 系统会自动过滤危险命令（如
rm -rf） - 会话过期: 会话有过期时间，过期后无法接受命令
- 邮件加密: 使用 SSL/TLS 加密的 IMAP 连接
- 密码安全: 使用应用专用密码而非主密码
故障排查
常见问题
-
无法连接到邮件服务器
- 检查 IMAP 是否已启用
- 验证服务器地址和端口
- 确认防火墙设置
-
邮件未被处理
- 检查发件人是否在白名单中
- 验证邮件主题格式
- 查看日志中的错误信息
-
命令未执行
- 确认 Claude Code 进程正在运行
- 检查会话是否已过期
- 验证命令格式是否正确
查看日志
# 启动时查看详细日志
LOG_LEVEL=debug npm run relay:pty
# 查看 PTY 输出
PTY_OUTPUT_LOG=true npm run relay:pty
测试命令
# 测试邮件解析
npm run relay:test
# 手动启动（调试模式）
INJECTION_MODE=pty LOG_LEVEL=debug node src/relay/relay-pty.js
最佳实践
- 使用专用邮箱: 为 TaskPing 创建专用邮箱账号
- 定期清理: 定期清理过期会话和已处理邮件
- 命令简洁: 保持命令简短明确
- 及时回复: 在会话过期前回复邮件
- 安全优先: 不要在邮件中包含敏感信息
集成到现有项目
如果您想将邮件回复功能集成到现有的 Claude Code 工作流：
- 在发送提醒时创建会话：
const token = generateToken();
const session = {
type: 'pty',
createdAt: Math.floor(Date.now() / 1000),
expiresAt: Math.floor((Date.now() + 3600000) / 1000),
cwd: process.cwd()
};
saveSession(token, session);
- 在邮件主题中包含 Token：
const subject = `[TaskPing #${token}] ${taskDescription}`;
- 启动 PTY Relay 服务监听回复
相关文档
支持
如有问题，请查看：
- 项目 Issue: https://github.com/JessyTsui/TaskPing/issues
- 详细日志:
LOG_LEVEL=debug npm run relay:pty