knowledge/xhs/README.md

内容识别脚本使用说明

功能描述

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

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

环境配置

环境变量配置

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

# 飞书配置
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

cd xhs
python content_identify.py

运行时动态传入表格ID

cd xhs
python content_identify.py tblNdje7z6Cf3hax

其他命令行选项

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

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

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

2. 在代码中调用

from xhs.content_identify import ContentIdentifier

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

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

3. 运行测试脚本

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

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. 字段名称不匹配

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

调试模式

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