# 内容识别脚本使用说明

## 功能描述

`content_identify.py` 脚本实现了以下功能：

1. **读取飞书表格数据**：从指定的飞书多维表格中读取数据
2. **调用Coze工作流**：对每条记录调用Coze工作流进行内容识别
3. **结果写回**：将Coze返回的识别结果写回飞书表格

## 环境配置

### 环境变量配置

在 `.env` 文件中设置以下环境变量：

```bash
# 飞书配置
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_FILE_TOKEN=your_file_token
FEISHU_TABLE_ID=your_table_id    # 可选，也可在运行时传入

# 可选：自定义字段名称
FEISHU_INPUT_FIELD=抓取结果      # 输入内容字段名
FEISHU_OUTPUT_FIELD=识别结果     # 输出结果字段名
```

**注意**：`FEISHU_TABLE_ID` 可以通过以下方式设置（优先级从高到低）：
1. 命令行参数：`python content_identify.py tblNdje7z6Cf3hax`
2. 环境变量：`FEISHU_TABLE_ID=your_table_id`

### 飞书表格结构

飞书表格应包含以下字段：
- **标题**：内容的标题
- **抓取结果**：需要识别的内容文本
- **图片链接**：相关的图片URL列表
- **识别结果**：Coze工作流的识别结果（会自动填充）

## 使用方法

### 1. 直接运行脚本

#### 使用环境变量中的表格ID
```bash
cd xhs
python content_identify.py
```

#### 运行时动态传入表格ID
```bash
cd xhs
python content_identify.py tblNdje7z6Cf3hax
```

#### 其他命令行选项
```bash
# 试运行模式（只显示会处理的记录，不实际调用API）
python content_identify.py tblNdje7z6Cf3hax --dry-run

# 从指定分页token开始处理
python content_identify.py tblNdje7z6Cf3hax --page-token VEBsbCfaWa3gF3slQILc6Rybnde

# 查看帮助信息
python content_identify.py --help
```

### 2. 在代码中调用

```python
from xhs.content_identify import ContentIdentifier

# 使用环境变量中的表格ID
identifier = ContentIdentifier()
identifier.process_all_records()

# 或者动态传入表格ID
identifier = ContentIdentifier(table_id='tblNdje7z6Cf3hax')
identifier.process_all_records()
```

### 3. 运行测试脚本

在运行主脚本之前，建议先运行测试脚本验证配置：

```bash
cd xhs
python test_content_identify.py
```

测试脚本会检查：
- 环境变量配置
- 飞书API连接
- Coze API连接
- ContentIdentifier类初始化

## 脚本特性

### 智能处理
- **跳过已处理记录**：如果某条记录已有识别结果，会自动跳过
- **空内容检查**：没有输入内容的记录会被跳过
- **分页处理**：支持大量数据的分页处理

### 错误处理
- **API调用失败**：Coze API调用失败时会记录错误信息
- **数据提取失败**：无法提取数据时会记录详细错误
- **网络异常**：网络问题时会自动重试

### 性能优化
- **API限制**：每次调用后添加1秒延迟，避免触发API限制
- **批量处理**：支持批量获取和更新记录
- **内存优化**：分页处理避免内存溢出

## 输出日志

脚本运行时会输出详细的处理日志：

```
开始处理飞书表格 tblxxxxxxxxx 中的所有记录
获取到 10 条记录
处理记录 recxxxxxxxxx
标题: 这是一个测试标题...
内容长度: 1234 字符
图片数量: 3
正在调用Coze工作流，标题: 这是一个测试标题...
Coze工作流调用成功
已更新记录 recxxxxxxxxx
处理完成！总共处理 10 条记录，成功 10 条
```

## 故障排除

### 常见问题

1. **环境变量未设置**
   - 确保所有必需的环境变量都已正确设置
   - 检查 `.env` 文件是否存在且格式正确

2. **飞书API权限问题**
   - 检查 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 是否正确
   - 确认应用有访问多维表格的权限

3. **Coze API调用失败**
   - 检查Coze工作流ID是否正确
   - 确认API密钥有效且有调用权限

4. **字段名称不匹配**
   - 检查飞书表格中的字段名称是否与配置一致
   - 可以通过环境变量自定义字段名称

### 调试模式

如需更详细的调试信息，可以修改脚本中的日志级别或添加更多打印语句。