214 lines
5.7 KiB
Markdown
214 lines
5.7 KiB
Markdown
# TaskPing - 智能邮件自动化 Claude Code 助手
|
||
|
||
TaskPing 是一个智能的邮件自动化工具，实现了 Claude Code 与邮件系统的深度集成。通过监听邮件回复，自动将回复内容输入到对应的 Claude Code 会话中执行，让你可以在任何地方通过邮件远程控制 Claude Code。
|
||
|
||
## 🚀 核心功能
|
||
|
||
### 📧 智能邮件通知
|
||
- **自动检测**: 基于 Claude Code 官方 hooks 机制，自动识别任务完成和等待输入状态
|
||
- **实时通知**: 任务完成时自动发送邮件，包含完整的用户问题和 Claude 回复内容
|
||
- **会话绑定**: 邮件与特定的 tmux 会话绑定，确保回复到正确的 Claude Code 窗口
|
||
|
||
### 🔄 邮件回复自动执行
|
||
- **远程控制**: 直接回复邮件，内容自动输入到对应的 Claude Code 会话中
|
||
- **智能注入**: 自动检测 tmux 会话状态，将命令精确注入到正确的窗口
|
||
- **防重复处理**: 实现邮件去重机制，避免重复处理同一封邮件
|
||
|
||
### 🛡️ 稳定性保障
|
||
- **单实例运行**: 确保只有一个邮件监听进程运行，避免重复处理
|
||
- **状态管理**: 完善的会话状态跟踪和错误恢复机制
|
||
- **安全验证**: 邮件来源验证，确保只处理授权用户的回复
|
||
|
||
## 📦 快速安装
|
||
|
||
### 1. 克隆项目
|
||
```bash
|
||
git clone https://github.com/your-username/TaskPing.git
|
||
cd TaskPing
|
||
npm install
|
||
```
|
||
|
||
### 2. 配置邮箱
|
||
```bash
|
||
npm run config
|
||
```
|
||
按照提示配置你的邮箱信息（SMTP 和 IMAP）。
|
||
|
||
### 3. 配置 Claude Code 钩子
|
||
将以下内容添加到 `~/.claude/settings.json` 的 `hooks` 部分：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"Stop": [{
|
||
"matcher": "*",
|
||
"hooks": [{
|
||
"type": "command",
|
||
"command": "node /path/to/TaskPing/taskping.js notify --type completed",
|
||
"timeout": 5
|
||
}]
|
||
}],
|
||
"SubagentStop": [{
|
||
"matcher": "*",
|
||
"hooks": [{
|
||
"type": "command",
|
||
"command": "node /path/to/TaskPing/taskping.js notify --type waiting",
|
||
"timeout": 5
|
||
}]
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 全局安装 claude-control 命令
|
||
```bash
|
||
node install-global.js
|
||
```
|
||
|
||
### 5. 启动邮件监听服务
|
||
```bash
|
||
npm run relay:pty
|
||
```
|
||
|
||
## 🎮 使用方法
|
||
|
||
### 1. 创建 Claude Code 会话
|
||
```bash
|
||
# 在任何目录下都可以运行
|
||
claude-control --session project-name
|
||
```
|
||
|
||
### 2. 正常使用 Claude Code
|
||
在 tmux 会话中正常与 Claude 对话：
|
||
```
|
||
> 请帮我分析这个项目的代码结构
|
||
|
||
Claude 回复...
|
||
```
|
||
|
||
### 3. 自动邮件通知
|
||
当 Claude 完成任务时，你会收到包含完整对话内容的邮件通知。
|
||
|
||
### 4. 邮件回复控制
|
||
直接回复邮件，输入下一个指令：
|
||
```
|
||
请继续优化代码性能
|
||
```
|
||
|
||
### 5. 自动执行
|
||
你的回复会自动注入到对应的 Claude Code 会话中并执行。
|
||
|
||
## 🔧 项目架构
|
||
|
||
```
|
||
TaskPing/
|
||
├── src/
|
||
│ ├── channels/email/
|
||
│ │ └── smtp.js # SMTP 邮件发送
|
||
│ ├── core/
|
||
│ │ ├── config.js # 配置管理
|
||
│ │ ├── logger.js # 日志系统
|
||
│ │ └── notifier.js # 通知协调器
|
||
│ ├── data/
|
||
│ │ ├── session-map.json # 会话映射表
|
||
│ │ └── processed-messages.json # 已处理邮件记录
|
||
│ ├── relay/
|
||
│ │ └── relay-pty.js # 邮件监听和 PTY 注入服务
|
||
│ └── utils/
|
||
│ └── tmux-monitor.js # Tmux 会话监控
|
||
├── taskping.js # 主入口文件
|
||
├── claude-control.js # Claude Code 会话管理
|
||
├── start-relay-pty.js # 邮件监听服务启动器
|
||
└── install-global.js # 全局安装脚本
|
||
```
|
||
|
||
## 🛠️ 核心技术实现
|
||
|
||
### 邮件监听与处理
|
||
- 使用 `node-imap` 监听 IMAP 邮箱新邮件
|
||
- 实现邮件去重机制（基于 UID、messageId 和内容哈希）
|
||
- 异步事件处理，避免竞态条件
|
||
|
||
### 会话管理
|
||
- Tmux 会话自动检测和命令注入
|
||
- 会话状态持久化存储
|
||
- 支持多会话并发处理
|
||
|
||
### 通知系统
|
||
- 自动捕获当前 tmux 会话的用户问题和 Claude 回复
|
||
- 生成包含完整对话内容的邮件通知
|
||
- 支持多种通知渠道（桌面通知、邮件等）
|
||
|
||
## 🔍 故障排除
|
||
|
||
### 邮件重复处理问题
|
||
确保只运行一个邮件监听进程：
|
||
```bash
|
||
# 检查运行状态
|
||
ps aux | grep relay-pty
|
||
|
||
# 停止所有进程
|
||
pkill -f relay-pty
|
||
|
||
# 重新启动
|
||
npm run relay:pty
|
||
```
|
||
|
||
### 命令注入失败
|
||
检查 tmux 会话状态：
|
||
```bash
|
||
# 查看所有会话
|
||
tmux list-sessions
|
||
|
||
# 检查会话内容
|
||
tmux capture-pane -t session-name -p
|
||
```
|
||
|
||
### 邮件配置问题
|
||
测试邮件连接：
|
||
```bash
|
||
# 测试 SMTP
|
||
node -e "
|
||
const config = require('./config/user.json');
|
||
console.log('SMTP Config:', config.email.config.smtp);
|
||
"
|
||
|
||
# 测试 IMAP
|
||
node -e "
|
||
const config = require('./config/user.json');
|
||
console.log('IMAP Config:', config.email.config.imap);
|
||
"
|
||
```
|
||
|
||
## 🎯 使用场景
|
||
|
||
### 远程编程工作流
|
||
1. 在办公室启动一个 Claude Code 代码审查任务
|
||
2. 下班回家，收到邮件"代码审查完成，发现3个问题"
|
||
3. 回复邮件"请修复第一个问题"
|
||
4. Claude 自动开始修复，完成后再次发送邮件通知
|
||
5. 继续回复邮件进行下一步操作
|
||
|
||
### 长时间任务监控
|
||
1. 启动大型项目重构任务
|
||
2. Claude 分步骤完成各个模块
|
||
3. 每个阶段完成都发送邮件通知进度
|
||
4. 通过邮件回复指导下一步方向
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 本项目
|
||
2. 创建功能分支：`git checkout -b feature/new-feature`
|
||
3. 提交更改：`git commit -am 'Add new feature'`
|
||
4. 推送分支：`git push origin feature/new-feature`
|
||
5. 提交 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT License 开源协议。
|
||
|
||
---
|
||
|
||
**让 Claude Code 工作流程更加智能高效！**
|
||
|
||
如果这个项目对你有帮助，请给我们一个 ⭐！ |