文件关键信息提取器 (File Key Info Extractor)

XpertAI 平台插件 — 从文件中自动提取结构化关键信息

📖 简介

文件关键信息提取器 是一个 XpertAI 平台中间件插件，能够读取多种格式的文件（PDF、DOCX、TXT、MD 等），并自动提取以下结构化关键信息：

• 文件标题 — 自动识别文档标题
• 核心摘要 — 提取文档核心内容的精炼摘要
• 关键要点 — 提取文档中的要点和列表项
• 重要数据/指标 — 识别货币金额、百分比、数量指标、变化趋势等
• 关键实体 — 识别人物、组织、地点等命名实体
• 时间线/日期 — 提取文档中的时间线和关键日期事件

输出格式支持 结构化 JSON 和 Markdown 报告 两种模式。

🎯 适用场景

• 文档智能分析与摘要生成
• 报告/合同/论文等文件的关键信息快速提取
• 批量文件处理与信息归档
• 知识库构建与文档索引
• 智能体文件理解与问答辅助

📁 目录结构

file-keyinfo-extractor/
├── .xpertai-plugin/
│   └── plugin.json                    # 插件清单
├── index.js                           # 插件入口（CommonJS）
├── package.json                       # 项目配置
├── README.md                          # 项目文档
├── src/
│   ├── file-keyinfo-extractor.module.ts    # NestJS 模块
│   ├── file-keyinfo-extractor.service.ts   # 核心服务
│   ├── schemas/
│   │   └── config.schema.ts                # 配置 Schema (zod)
│   ├── middlewares/
│   │   └── file-keyinfo-extractor.middleware.ts  # 中间件策略
│   └── mcp/
│       ├── file-keyinfo-extractor.mcp-server.ts  # MCP Server 定义
│       └── tools/
│           └── extract-file-keyinfo.tool.ts      # MCP Tool Schema
├── resources/
│   └── skills/
│       └── file-keyinfo-extract.skill.json       # Skill 资源
└── examples/
    └── request.example.json                      # 调用示例

🚀 安装与使用

npm 安装

npm install @timmy_hu/file-keyinfo-extractor

XpertAI 平台安装

通过 XpertAI 平台 API 安装：

curl -X POST http://10.161.48.53:3300/api/plugin \
  -H "Authorization: Bearer <token>" \
  -H "organization-id: <org-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "pluginName": "@timmy_hu/file-keyinfo-extractor",
    "version": "1.0.0",
    "source": "npm"
  }'

⚙️ 配置项

| 配置项 | 类型 | 默认值 | 必填 | 说明 | |--------|------|--------|------|------| | maxSummarySentences | number | 5 | 否 | 摘要最大句数（1-20） | | maxKeyPoints | number | 10 | 否 | 关键要点最大数量（1-50） | | defaultOutputFormat | string | "json" | 否 | 默认输出格式：json 或 markdown | | supportedExtensions | string[] | [".pdf", ".docx", ".txt", ".md"] | 否 | 支持的文件扩展名 | | maxBatchFiles | number | 20 | 否 | 批量处理最大文件数 | | maxImportantData | number | 20 | 否 | 重要数据最大提取数量 | | maxTimelineEntries | number | 15 | 否 | 时间线最大条目数 | | maxEntitiesPerCategory | number | 10 | 否 | 每类实体最大数量 |

🔧 Agent Middleware 工具列表

插件通过 FileKeyinfoExtractorMiddleware 中间件策略暴露以下 3 个智能体可直接调用的工具：

1. extract_file_keyinfo — 从文件提取关键信息

从指定文件路径读取文件内容并提取关键信息。

入参：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | filePath | string | ✅ | 文件路径 | | outputFormat | "json" | "markdown" | ❌ | 输出格式，默认 json | | maxSummarySentences | number | ❌ | 摘要最大句数 | | maxKeyPoints | number | ❌ | 关键要点最大数量 |

出参： 结构化 JSON 或 Markdown 报告

2. extract_text_keyinfo — 从文本提取关键信息

从给定的文本内容中提取关键信息。

入参：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | text | string | ✅ | 文本内容 | | outputFormat | "json" | "markdown" | ❌ | 输出格式，默认 json | | maxSummarySentences | number | ❌ | 摘要最大句数 | | maxKeyPoints | number | ❌ | 关键要点最大数量 |

出参： 结构化 JSON 或 Markdown 报告

3. extract_directory_keyinfo — 批量目录提取

批量读取指定目录下的所有支持格式文件并提取关键信息。

入参：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dirPath | string | ✅ | 目录路径 | | outputFormat | "json" | "markdown" | ❌ | 输出格式，默认 json | | fileExtensions | string[] | ❌ | 文件扩展名过滤列表 |

出参： 包含所有文件提取结果的 JSON 或 Markdown 报告

📋 返回值说明

JSON 格式

{
  "title": "文档标题",
  "summary": "核心摘要文本...",
  "keyPoints": ["要点1", "要点2", "..."],
  "importantData": [
    { "value": "5.2亿元", "type": "货币金额" },
    { "value": "23.5%", "type": "百分比" }
  ],
  "entities": {
    "people": ["张三", "李四"],
    "organizations": ["华为技术有限公司", "清华大学"],
    "locations": ["北京市", "上海市"],
    "other": []
  },
  "timeline": [
    { "date": "2024-01-15", "event": "启动数字化转型项目" },
    { "date": "2024-06-20", "event": "完成B轮融资" }
  ],
  "metadata": {
    "textLength": 12345,
    "extractedAt": "2024-01-01T00:00:00.000Z",
    "wordCount": 5678
  }
}

Markdown 格式

输出为结构化的 Markdown 报告，包含标题、摘要、要点列表、数据表格、实体分类和时间线表格。

📝 调用示例

示例 1：从 PDF 提取关键信息

{
  "tool": "extract_file_keyinfo",
  "input": {
    "filePath": "/data/reports/annual-report-2024.pdf",
    "outputFormat": "json"
  }
}

示例 2：从文本提取关键信息

{
  "tool": "extract_text_keyinfo",
  "input": {
    "text": "# 项目报告\n\n2024年项目取得了显著进展...",
    "outputFormat": "markdown",
    "maxSummarySentences": 3
  }
}

示例 3：批量处理目录

{
  "tool": "extract_directory_keyinfo",
  "input": {
    "dirPath": "/data/documents/",
    "outputFormat": "json",
    "fileExtensions": [".pdf", ".docx", ".txt"]
  }
}

❌ 常见错误与处理

| 错误信息 | 原因 | 处理方式 | |----------|------|----------| | 文件不存在: /path/to/file | 文件路径不正确 | 检查文件路径是否正确 | | 不支持的文件格式: .xyz | 文件格式不在支持列表中 | 转换为支持的格式或使用文本格式 | | PDF 解析失败: ... | PDF 文件损坏或加密 | 检查 PDF 文件完整性 | | DOCX 解析失败: ... | DOCX 文件损坏 | 检查 DOCX 文件完整性 | | 文件内容为空或无法解析 | 文件内容为空 | 确认文件有实际内容 | | 目录不存在: /path/to/dir | 目录路径不正确 | 检查目录路径 |

🔒 安全注意事项

• 插件仅在本地文件系统操作，不会将文件内容上传到外部服务器
• 文件路径参数应确保在安全范围内，避免路径遍历攻击
• 批量处理时限制最大文件数量，防止资源耗尽
• 敏感文件应设置适当的文件权限
• 生产环境建议对文件路径进行白名单校验

📦 技术栈

• 运行时: Node.js
• 框架: NestJS
• 文件解析: pdf-parse (PDF), mammoth (DOCX)
• Schema 验证: zod
• 工具封装: @langchain/core
• 插件 SDK: @xpert-ai/plugin-sdk

📄 许可证

MIT