文本转附件

插件简介

将 AI 已确认的答复内容转换为多种专业格式文件（docx、xlsx、pdf、pptx、html、png、md、json、csv、xml、yaml、txt、rtf、svg 等），执行质量校验和文件大小检查后上传至文件服务，返回可供前端展示的文件 ID、下载链接等信息。

适用场景

• 用户要求将 AI 答复导出为 Word、Excel、PDF、PPT 等格式
• 用户要求生成专业报告、数据表格、演示文稿、信息图
• 用户要求根据经纬度或站点点位生成天地图静态地图 PNG
• 用户要求批量导出多种格式并获取下载链接
• 用户要求上传文件到文件服务并返回文件信息

目录结构

ai-reply-file-export/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 项目配置
├── README.md                    # 本文件
├── SKILL.md                     # Skill 兜底入口
├── src/
│   ├── shared/
│   │   ├── executor.js          # 共享业务执行器
│   │   └── types.js             # 共享类型定义
│   └── schemas/
│       ├── config.schema.js     # 配置 Schema（zod）
│       └── tool.schema.js       # 工具输入 Schema（zod）
├── resources/
│   └── skills/
│       └── ai-reply-file-export/
│           ├── SKILL.md         # 平台可发现 Skill
│           ├── skill.json       # 技能清单
│           └── examples/
│               └── request.example.json
├── scripts/
│   ├── sdk-shim.js              # SDK 兼容层
│   ├── check-plugin.js          # 自检脚本
│   ├── run-skill.js             # Skill 运行脚本
│   ├── invoke-tool.js           # 工具调用脚本
│   └── package-zip.js           # zip 打包脚本
└── examples/
    └── skill-input.example.json # Skill 输入示例

安装与构建

1. 安装依赖

npm install

2. 运行自检

npm run check

3. 发布安装

npm 方式：

npm publish --access public --registry https://registry.npmjs.org/

zip 方式：

npm run package:zip

配置项

| 配置 | 环境变量 | 默认值 | 必填 | 说明 | |------|----------|--------|------|------| | 文件服务地址 | FILE_SERVICE_BASE_URL | http://yuhang-test.fpi-inc.site:30080 | ✅ | 文件上传下载服务基础地址 | | 最大文件大小 | FILE_SERVICE_MAX_SIZE_MB | 50 | ❌ | 单文件最大 MB，超限阻止上传 | | 鉴权 Token | FILE_SERVICE_AUTH_TOKEN | （空） | ❌ | 文件服务 Bearer Token | | 天地图 API Key | TIANDITU_API_KEY | 86208f779380a2b1bd74a47b4d23d832 | ❌ | 天地图静态地图服务 API Key |

天地图静态图

将 formats 设置为 tianditu，并以 JSON 字符串传入点位数据。插件调用天地图 staticimage API，返回 PNG。

{
  "content": "{\"points\":[{\"lng\":120.15,\"lat\":30.28,\"name\":\"杭州站\"}],\"_zoom\":12}",
  "title": "站点分布图",
  "formats": "tianditu"
}

Agent Middleware 工具列表

1. export_and_upload_file

将 AI 答复内容导出为文件并上传至文件服务。

输入参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | content | string | ✅ | AI 已确认的答复内容 | | title | string | ❌ | 文档标题 | | fileName | string | ❌ | 文件名（不含扩展名） | | formats | string | string[] | ❌ | 目标格式，如 "xlsx,pdf" | | sections | array | ❌ | 结构化段落 | | metadata | object | ❌ | 元数据 |

返回值：

{
  "status": "success",
  "file": {
    "fileId": "abc123",
    "fileName": "报告_2024-01-15.docx",
    "fileType": "docx",
    "length": 57929,
    "downloadUrl": "http://host/file-base-server/api/v1/sys/download/abc123",
    "infoUrl": "http://host/file-base-server/api/v1/sys/info/abc123"
  }
}

2. list_file_categories

查询支持的文件类型分类及扩展名。

输入参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category | string | ❌ | 分类名：document/spreadsheet/slide/pdf/image/video/audio/markdown/other/all |

Skill 兜底运行

当平台无法直接调用 Agent Middleware Tool 时，可通过 Skill 脚本间接执行：

# 使用示例输入
node scripts/run-skill.js examples/skill-input.example.json

# 使用自定义 JSON
node scripts/run-skill.js '{"content":"Hello","title":"测试","formats":"md,txt"}'

# 通过工具调用脚本
node scripts/invoke-tool.js export_and_upload_file examples/skill-input.example.json
node scripts/invoke-tool.js list_file_categories '{"category":"all"}'

scripts 目录说明

| 脚本 | 用途 | 命令 | |------|------|------| | sdk-shim.js | SDK 兼容层，本地无宿主 SDK 时 mock 装饰器 | 被其他脚本自动加载 | | check-plugin.js | 插件自检，校验入口、依赖、工具、文件完整性 | npm run check | | run-skill.js | Skill 兜底运行，调用共享执行器 | npm run skill:run | | invoke-tool.js | 本地工具调用，按工具名和参数调用 | npm run tool:invoke | | package-zip.js | zip 打包，确保根目录结构正确 | npm run package:zip |

版本与 API 兼容说明

• Node.js: 20+
• @langchain/core: ^0.3.70（使用 tool() 从 @langchain/core/tools）
• zod: ^3.23.0（v3 兼容写法）
• @nestjs/common: ^10.0.0
• reflect-metadata: ^0.2.0
• @xpert-ai/plugin-sdk: ^3.14.0（peerDependency，由宿主提供）
• 本地脚本通过 scripts/sdk-shim.js 兼容本地缺失宿主 SDK 场景

首次运行顺序

1. npm install — 安装依赖
2. npm run check — 运行自检
3. 根据安装方式执行 npm 发布或 zip 打包

支持的文件格式

| 分类 | 可生成格式 | 不可生成格式（说明） | |------|-----------|---------------------| | 文档 | docx, txt, html, htm, rtf | doc（旧格式） | | 表格 | xlsx, csv, tsv | xls（旧格式） | | 幻灯片 | pptx | ppt（旧格式） | | PDF | pdf | - | | 图片 | png, jpg, jpeg, webp, gif, bmp, svg, echarts, tianditu | - | | Markdown | md, markdown | - | | 其他 | json, xml, yaml, yml, log | zip | | 视频 | - | mp4, mov, avi, mkv, webm（无法生成） | | 音频 | - | mp3, wav, m4a, aac, flac, ogg（无法生成） |

常见错误与处理

| 错误 | 原因 | 处理 | |------|------|------| | FILE_SIZE_EXCEEDED | 文件超过大小限制 | 精简内容、降低分辨率或提高限制值 | | 上传失败 HTTP xxx | 文件服务不可达 | 检查 FILE_SERVICE_BASE_URL 和网络 | | 不支持的格式 | 请求了无法生成的格式 | 更换为可支持格式 | | 缺少必填参数 content | 未提供内容 | 确保输入包含 content 字段 |

安全注意事项

• 只导出已确认的 AI 答复内容，不猜测或编造信息
• 不打印或泄露环境变量、认证信息、内部路径
• 文件大小校验在上传前执行，超限文件不会被上传
• 敏感配置通过环境变量或占位符注入，不硬编码
• 数学公式保留 LaTeX 语义，化学式正确保留上下标