207 lines
5.5 KiB
Markdown
207 lines
5.5 KiB
Markdown
# TaskPing 邮件功能架构设计
|
||
|
||
## 功能概述
|
||
|
||
实现邮件通知和远程命令执行功能，用户可以：
|
||
1. 接收 Claude Code 任务完成的邮件通知
|
||
2. 通过回复邮件来远程执行下一步命令
|
||
3. 在不坐在电脑前的情况下继续 Claude Code 对话
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||
│ Claude Code │ ──▶│ TaskPing CLI │ ──▶│ Email Channel │
|
||
│ (hooks) │ │ │ │ (SMTP Send) │
|
||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────┐ ┌─────────────────┐
|
||
│ Command Relay │◀───│ Email Listener │
|
||
│ Service │ │ (IMAP Receive) │
|
||
└──────────────────┘ └─────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────┐
|
||
│ Claude Code │
|
||
│ (stdin input) │
|
||
└──────────────────┘
|
||
```
|
||
|
||
## 核心组件
|
||
|
||
### 1. 邮件通知渠道 (Email Channel)
|
||
- **位置**: `src/channels/email/smtp.js`
|
||
- **功能**: 发送任务完成通知邮件
|
||
- **特性**:
|
||
- 支持多种 SMTP 配置
|
||
- 邮件模板化
|
||
- 会话 ID 生成和嵌入
|
||
- 安全回复指令
|
||
|
||
### 2. 邮件监听器 (Email Listener)
|
||
- **位置**: `src/relay/email-listener.js`
|
||
- **功能**: 监听和解析邮件回复
|
||
- **特性**:
|
||
- IMAP/POP3 邮件接收
|
||
- 邮件解析和命令提取
|
||
- 会话 ID 验证
|
||
- 安全检查
|
||
|
||
### 3. 命令中继服务 (Command Relay Service)
|
||
- **位置**: `src/relay/command-relay.js`
|
||
- **功能**: 管理命令队列和执行
|
||
- **特性**:
|
||
- 会话管理
|
||
- 命令队列
|
||
- Claude Code 集成
|
||
- 安全验证
|
||
|
||
### 4. 会话管理器 (Session Manager)
|
||
- **位置**: `src/relay/session-manager.js`
|
||
- **功能**: 管理 Claude Code 会话状态
|
||
- **特性**:
|
||
- 会话创建和跟踪
|
||
- 超时管理
|
||
- 状态持久化
|
||
|
||
## 数据流程
|
||
|
||
### 发送通知流程
|
||
1. Claude Code 触发 hook → TaskPing CLI
|
||
2. TaskPing 创建会话 ID 和通知
|
||
3. 邮件渠道发送包含会话信息的邮件
|
||
4. 会话管理器记录会话状态
|
||
|
||
### 命令执行流程
|
||
1. 用户回复邮件 → 邮件监听器接收
|
||
2. 解析邮件内容和会话 ID
|
||
3. 验证会话有效性和安全性
|
||
4. 将命令加入执行队列
|
||
5. 命令中继服务执行命令
|
||
|
||
## 邮件模板设计
|
||
|
||
### 通知邮件模板
|
||
```
|
||
主题: [TaskPing] Claude Code 任务完成 - {project}
|
||
|
||
{user_name}，您好！
|
||
|
||
Claude Code 已完成任务，正在等待您的下一步指令。
|
||
|
||
项目: {project}
|
||
时间: {timestamp}
|
||
状态: {status}
|
||
|
||
要继续对话，请直接回复此邮件，在邮件正文中输入您的指令。
|
||
|
||
示例回复:
|
||
"请继续优化代码"
|
||
"生成单元测试"
|
||
"解释这个函数的作用"
|
||
|
||
---
|
||
会话ID: {session_id}
|
||
安全提示: 请勿转发此邮件，会话将在24小时后过期
|
||
```
|
||
|
||
### 回复解析规则
|
||
- 提取邮件正文作为 Claude Code 指令
|
||
- 忽略邮件签名和引用内容
|
||
- 验证会话 ID 有效性
|
||
- 检查指令安全性
|
||
|
||
## 安全机制
|
||
|
||
### 1. 会话验证
|
||
- 唯一会话 ID (UUID v4)
|
||
- 24小时过期时间
|
||
- 用户邮箱验证
|
||
|
||
### 2. 命令安全
|
||
- 危险命令黑名单
|
||
- 长度限制 (< 1000 字符)
|
||
- 特殊字符过滤
|
||
|
||
### 3. 频率限制
|
||
- 每会话最多 10 次命令
|
||
- 每小时最多 5 个新会话
|
||
- 异常行为检测
|
||
|
||
## 配置结构
|
||
|
||
### 邮件配置 (config/channels.json)
|
||
```json
|
||
{
|
||
"email": {
|
||
"type": "email",
|
||
"enabled": true,
|
||
"config": {
|
||
"smtp": {
|
||
"host": "smtp.gmail.com",
|
||
"port": 587,
|
||
"secure": false,
|
||
"auth": {
|
||
"user": "your-email@gmail.com",
|
||
"pass": "your-app-password"
|
||
}
|
||
},
|
||
"imap": {
|
||
"host": "imap.gmail.com",
|
||
"port": 993,
|
||
"secure": true,
|
||
"auth": {
|
||
"user": "your-email@gmail.com",
|
||
"pass": "your-app-password"
|
||
}
|
||
},
|
||
"from": "TaskPing <your-email@gmail.com>",
|
||
"to": "your-email@gmail.com",
|
||
"template": {
|
||
"subject": "[TaskPing] Claude Code 任务完成 - {{project}}",
|
||
"checkInterval": 30
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 中继配置 (config/relay.json)
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"security": {
|
||
"sessionTimeout": 86400,
|
||
"maxCommandsPerSession": 10,
|
||
"maxSessionsPerHour": 5,
|
||
"commandMaxLength": 1000
|
||
},
|
||
"claudeCode": {
|
||
"detectMethod": "ps",
|
||
"inputMethod": "stdin"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实现计划
|
||
|
||
1. **Phase 1**: 邮件发送功能
|
||
- 实现 SMTP 邮件渠道
|
||
- 创建邮件模板系统
|
||
- 配置管理界面
|
||
|
||
2. **Phase 2**: 邮件接收功能
|
||
- IMAP 邮件监听器
|
||
- 邮件解析和命令提取
|
||
- 会话管理器
|
||
|
||
3. **Phase 3**: 命令中继功能
|
||
- 命令队列系统
|
||
- Claude Code 集成
|
||
- 安全验证机制
|
||
|
||
4. **Phase 4**: 测试和优化
|
||
- 端到端测试
|
||
- 错误处理完善
|
||
- 性能优化 |