feishu_screen/README.md

# Screen2Feishu - AI任务管理Web应用

## 项目简介

Screen2Feishu是一个基于AI技术的任务管理Web应用，能够自动分析截图和任务描述，识别任务信息并写入飞书多维表格。

## 核心功能

### 📸 图片上传分析

- 上传截图，AI自动分析图片内容
- 识别任务描述、优先级、发起人等信息
- 自动匹配飞书用户，处理重名情况
- 将分析结果写入飞书多维表格

### ⚙️ 智能配置

- 内存处理模式：不保存图片文件，节省存储空间
- 用户匹配机制：自动匹配飞书用户列表
- 随机匹配回退：重名时随机选择最近联系人
- 缓存管理：自动管理用户缓存，提高匹配效率

### 📊 实时反馈

- 显示AI分析结果
- 显示操作状态和进度
- 系统配置信息展示
- 用户缓存状态监控

## 快速开始

### 1. 环境准备

```bash
# 安装Python依赖
pip install -r requirements.txt
```

### 2. 配置文件

复制配置文件模板并编辑：

```bash
cp config.example.yaml config.yaml
```

编辑 `config.yaml` 文件，填入你的配置：

```yaml
ai:
  api_key: "your_api_key"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o"

feishu:
  app_id: "your_app_id"
  app_secret: "your_app_secret"
  app_token: "your_app_token"
  table_id: "your_table_id"

system:
  memory_processing: false  # 是否启用内存处理
  post_process: "keep"  # 文件处理策略

  user_matching:
    enabled: true  # 是否启用用户匹配
    fallback_to_random: true  # 是否启用随机匹配回退
    cache_enabled: true  # 是否启用缓存
    cache_file: "./data/user_cache.json"
```

### 3. 启动应用

```bash
# 使用启动脚本（推荐）
python start_web_app.py

# 或者直接启动
python web_app.py
```

### 4. 访问界面

打开浏览器，访问：`http://localhost:5000`

## 使用指南

### 图片上传分析

1. **选择图片**：点击上传区域或拖拽图片到指定区域
2. **上传分析**：点击"上传并分析"按钮
3. **查看结果**：系统会显示AI分析结果和操作状态
4. **自动处理**：任务会自动写入飞书多维表格

### AI分析结果

系统会识别以下信息：

- **任务描述**：从图片中提取的任务内容
- **优先级**：紧急、较紧急、一般、普通
- **状态**：未开始、进行中、已完成
- **发起人**：识别到的任务发起人姓名
- **部门**：发起人所属部门
- **开始日期**：任务开始时间
- **截止日期**：任务截止时间

### 用户匹配机制

1. **自动匹配**：系统从飞书API获取用户列表
2. **精确匹配**：根据姓名精确匹配用户
3. **模糊匹配**：根据姓名包含关系匹配用户
4. **随机回退**：重名时随机选择最近联系人
5. **人工确认**：无法匹配时标记为待确认

## 配置说明

### 内存处理模式

```yaml
system:
  memory_processing: true  # 启用内存处理，不保存图片文件
```

**优点**：

- 不占用磁盘空间
- 处理速度更快
- 隐私保护更好

**缺点**：

- 无法保留原始截图
- 无法回溯分析过程

### 用户匹配配置

```yaml
system:
  user_matching:
    enabled: true  # 启用用户匹配
    fallback_to_random: true  # 启用随机匹配回退
    cache_enabled: true  # 启用缓存
    cache_file: "./data/user_cache.json"  # 缓存文件路径
```

**缓存机制**：

- 自动从飞书API获取用户列表
- 缓存有效期24小时
- 支持手动刷新缓存

### 文件处理策略

```yaml
system:
  post_process: "keep"  # 保留原始文件
  # post_process: "delete"  # 删除原始文件
  # post_process: "move"  # 移动到processed_images目录
```

## API接口

### 1. 上传图片分析

**接口**：`POST /api/upload`

**请求**：

```javascript
// 使用FormData上传图片
const formData = new FormData();
formData.append('image', file);

fetch('/api/upload', {
    method: 'POST',
    body: formData
});
```

**响应**：

```json
{
  "success": true,
  "message": "任务已成功添加到飞书",
  "ai_result": {
    "task_description": "任务描述",
    "priority": "紧急",
    "status": "未开始",
    "initiator": "张三",
    "department": "研发部",
    "start_date": "2026-03-03",
    "due_date": "2026-03-10",
    "任务发起方": {"id": "user_123"},
    "任务发起方.部门": "研发部"
  }
}
```

### 2. 获取用户缓存信息

**接口**：`GET /api/user_cache`

**响应**：

```json
{
  "success": true,
  "stats": {
    "user_count": 10,
    "recent_contact_count": 5,
    "cache_age_hours": 0.5,
    "is_expired": false
  }
}
```

### 3. 获取配置信息

**接口**：`GET /api/config`

**响应**：

```json
{
  "success": true,
  "config": {
    "memory_processing": false,
    "user_matching_enabled": true,
    "fallback_to_random": true,
    "cache_enabled": true,
    "post_process": "keep"
  }
}
```

## 界面说明

### 主界面布局

```
┌─────────────────────────────────────────────────────────┐
│                    Screen2Feishu                        │
├─────────────────────────────────────────────────────────┤
│  统计信息: 用户缓存 | 最近联系人 | 缓存状态             │
├──────────────────────┬──────────────────────────────────┤
│  📸 图片上传分析     │  ⚙️ 系统配置                     │
│                      │                                  │
│  [上传区域]          │  内存处理: 启用/禁用             │
│  文件名: xxx         │  用户匹配: 启用/禁用             │
│  [上传] [清空]       │  随机匹配: 启用/禁用             │
│                      │  缓存功能: 启用/禁用             │
│  上传状态:           │  文件处理: keep/delete/move      │
│  [状态信息]          │                                  │
│                      │  📝 状态日志                     │
│  AI分析结果:         │  [日志信息]                     │
│  [分析结果]          │                                  │
└──────────────────────┴──────────────────────────────────┘
```

### 状态指示

- **绿色**：成功状态
- **黄色**：警告状态（待确认、随机匹配等）
- **红色**：错误状态
- **蓝色**：信息状态

### 日志系统

系统会记录所有操作的日志，包括：

- 文件上传状态
- AI分析结果
- 用户匹配过程
- 飞书写入结果
- 错误信息

## 使用场景

### 场景1：截图转任务

1. 从聊天记录、邮件或文档中截图
2. 上传截图到Web界面
3. AI自动分析截图内容
4. 生成任务并写入飞书表格

### 场景2：批量处理

1. 准备多个截图文件
2. 逐个上传分析
3. 系统自动处理并写入飞书

### 场景3：实时监控

1. 配置监控文件夹
2. 新截图自动触发分析
3. 实时更新飞书表格

## 故障排除

### 1. 无法启动应用

**问题**：`ModuleNotFoundError`

**解决**：

```bash
pip install -r requirements.txt
```

### 2. AI分析失败

**问题**：API密钥错误或网络问题

**解决**：

- 检查 `config.yaml` 中的API密钥
- 检查网络连接
- 查看浏览器控制台错误信息

### 3. 飞书写入失败

**问题**：飞书API权限不足

**解决**：

- 检查飞书应用权限
- 验证 `app_id`、`app_secret`、`app_token`、`table_id`
- 查看日志中的详细错误信息

### 4. 用户匹配失败

**问题**：无法获取用户列表或匹配失败

**解决**：

- 检查飞书API权限（用户列表读取）
- 检查缓存文件路径
- 查看日志了解详细错误

## 技术架构

### 前端技术

- **HTML5**：语义化结构
- **CSS3**：现代样式，响应式设计
- **JavaScript**：异步请求，实时更新

### 后端技术

- **Flask**：轻量级Web框架
- **OpenAI API**：AI图像分析
- **飞书API**：用户管理和表格写入
- **用户缓存**：提高匹配效率

### 数据流

```
用户上传图片 → Web服务器接收 → AI分析 → 用户匹配 → 飞书写入 → 返回结果
```

## 项目结构

```
Screen2Feishu/
├── web_app.py              # Web应用入口
├── start_web_app.py        # 启动脚本
├── config.yaml             # 配置文件
├── requirements.txt        # Python依赖
├── templates/
│   └── index.html         # Web界面
├── services/
│   ├── ai_service.py      # AI服务
│   └── feishu_service.py  # 飞书服务
├── utils/
│   ├── user_cache.py      # 用户缓存
│   ├── config_loader.py   # 配置加载
│   ├── logger.py          # 日志工具
│   └── notifier.py        # 通知工具
├── data/                  # 数据目录
├── monitor_images/        # 监控图片
└── processed_images/      # 已处理图片
```

## 注意事项

1. **安全**：妥善保管API密钥，不要泄露
2. **权限**：确保飞书应用有必要的API权限
3. **网络**：保持网络连接稳定
4. **存储**：注意磁盘空间使用
5. **隐私**：敏感信息不要在日志中显示

## 更新日志

### v1.0.0

- ✅ 基础Web界面
- ✅ 图片上传分析
- ✅ AI自动识别
- ✅ 用户匹配机制
- ✅ 飞书集成
- ✅ 实时状态反馈
- ✅ 日志系统
- ✅ 配置管理

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交代码
4. 创建Pull Request

## 许可证

MIT License

## 联系方式

如有问题或建议，请通过GitHub Issues反馈。

---

**Screen2Feishu** - 让AI帮你管理任务 🚀