结构化信息提取工具

项目简介

本项目是一个结构化信息提取工具，可以从用户提供的邮件文件（eml、msg格式）和Excel文件中按照统一的信息项规格提取信息，并生成标准的Excel文本。

工具通过自动化处理，能够显著提升人力资源服务方处理客户入职、离职等人员信息的效率，减少人工录入工作量，降低错误率，并支持灵活适配客户多变的信息格式。

AI驱动的开发模式

本项目采用AI协作开发模式，运用Spec Coding（规范驱动开发）方法论进行开发。这种开发方式强调先制定清晰的规范文档，再让AI根据规范生成代码，确保开发过程的可控性和结果的可预测性。

Spec Coding 开发流程

我们的开发流程遵循以下六个步骤：

1. 需求梳理与规范制定：向AI提供文档模板和开发规范
2. 需求传达与方案设计：用自然语言向AI描述功能需求，生成proposal.md
3. 方案审查与确认：检查并修订AI生成的需求和技术方案
4. AI驱动代码实现：AI根据spec文档和tasks清单逐步实现代码
5. 验证测试：人工审核AI生成的代码并执行测试
6. 规范归档：将验证通过的功能文档迁移到标准spec目录

这种开发模式不仅提高了开发效率，还确保了代码质量和文档的规范性。

核心功能

1. 多格式邮件处理：支持处理eml和msg格式的邮件文件，包括邮件正文和附件
2. Excel文件解析：支持解析xls和xlsx格式的Excel文件，自动识别表头并提取数据
3. 智能信息提取：
   • 使用大语言模型从邮件正文中提取结构化信息
   • 使用规则+AI的方式处理Excel表格数据
4. 标准化输出：将提取的信息按照统一格式输出为标准的Excel文件

支持的输入格式

• 邮件文件：eml、msg
• 表格文件：xls、xlsx

输出格式

• 标准化Excel文件，包含统一的信息项字段

环境配置

cp env.example .env

编辑.env配置对应大模型的服务接口和api_key

使用方法

准备工作目录 ─ workdir    ├── source    ├── processing └── destination

命令行方式

1. 将需要处理的邮件文件（eml、msg）或Excel文件放入 source 目录
2. 运行命令：uv run info-extract --work-dir [workdir path]
3. 程序会自动处理所有文件，并将结果输出到 destination 目录

图形界面方式

运行命令启动图形界面： uv run info-ui --work-dir [workdir path] 你可以通过UI界面：

• 浏览工作目录中的文件
• 选择需要处理的文件
• 启动处理任务
• 查看处理进度和结果
• 管理和配置信息项规格

处理流程

%% 本地桌面的结构化信息提取工具

flowchart LR
    id1[\源文件\]
    id1-->extract([info_extract])
    extract-->f[\标准化Excel\]

Loading

配置管理与Profile功能

本工具支持Profile配置管理，允许用户定义和切换不同的配置集，以适应不同项目的处理需求。

Profile功能特性

1. 多配置集支持：可定义多个Profile，每个Profile包含独立的信息项定义、示例数据和提取规则
2. 动态关键列配置：通过Profile Attributes功能，可以配置数据处理的关键列名（如"姓名"、"Name"等），而不再使用硬编码值
3. 快速切换：通过UI界面或API可以快速在不同Profile间切换
4. 数据隔离：不同Profile的数据完全隔离，互不影响
5. 向后兼容：现有配置自动归入默认Profile，确保升级后功能正常

Profile管理

• 通过UI界面可以创建、删除和管理多个Profiles
• 每个Profile可独立配置信息项规格
• 支持不同Profile间的快速切换
• 适合不同客户或不同项目类型的配置管理

信息项规格（默认Profile）

工具默认按照以下统一信息项规格提取信息：

• 作业：入职/离职/变更
• 证件号码
• 姓名
• 客户名称
• 户籍
• 用工模式
• 入职日期
• 合同终止日期
• 离职日期
• 社保缴纳城市
• 社保基数
• 公积金基数
• 社保最后缴纳月
• 公积金最后缴纳月
• 成本中心
• 内部工号
• 备注

技术架构

本工具基于Python开发，主要依赖包括：

• msg-parser：用于解析Microsoft Outlook的msg文件
• extract-msg：用于处理msg格式邮件文件
• openpyxl：用于处理Excel文件
• pandas：用于数据处理
• pydantic-ai：用于AI信息提取
• langextract：用于文本信息提取

错误处理

• 程序会自动处理各种文件格式的异常情况
• 处理失败的文件会被移动到 error 目录
• 所有处理过程和错误信息都会记录在日志中

设计文档

项目的详细设计文档位于 docs/ 目录中，包括：

• introduction.md: Spec Coding 协作开发方法介绍，详细描述了我们如何使用AI协作开发此工具
• extract.md: 智能Excel数据标准化技术方案，涵盖大模型SQL生成、语义匹配及图结构映射关系模型
• ui/: UI界面相关的静态资源文件
• llms.txt: 大语言模型相关配置
• specs/: 核心模块设计文档（规范归档目录）
  • config/: 配置模块规格
    • spec.md: 信息项定义、Profile配置管理、划词标注功能设计
    • mark_extracts/: 划词标注功能相关设计文档
  • extract/: 信息提取模块规格
    • spec.md: 文本分词、语义匹配、BERT模型标准化设计
  • routing/: 路由编排模块规格
    • spec.md: 文件处理流程、节点编排、状态流转设计
    • nodes/: 各处理节点详细设计（文件识别、邮件提取、Excel分类与读取、数据映射、导出等）
  • ui/: UI界面模块规格
    • spec.md: Web界面、任务管理、流式进度、配置管理设计
    • task_cancel_spec.md: 任务取消功能设计
    • templates_spec.md: UI模板规范

AI协作开发说明

本项目开发过程记录在 docs/introduction.md 中，详细描述了我们如何使用AI协作开发此工具，以及Spec Coding方法论的应用实践。

开发环境

项目使用 uv 做Python依赖管理：

• 添加依赖包: uv add {依赖包}
• 程序运行: uv run {程序入口}
• 单元测试: uv run -m unittest ./tests/xxx.py

目录结构说明

• config: 参数、提示词等配置信息
• docs: 设计文档，包含specs和changes目录
• src: Python程序源码
• tests: 单元测试
• log: 日志

项目价值

1. 效率提升：自动化处理各类文档，大幅减少人工录入时间
2. 错误降低：通过标准化的处理流程，减少人为操作失误
3. 灵活适配：能够处理多样化的输入格式，适应不同客户的文件结构
4. 创新实践：验证了AI协作开发在实际项目中的可行性和优势