@timmy_hu/text-to-word

v1.0.0

Published

3 months ago

将AI答复的文本内容或Markdown格式内容转换为美观的Word文档，并上传到文件服务

0High
0Medium
0Low

timmy_hu

xpertai plugin word docx markdown text converter middleware

文本转Word插件 (Text to Word Plugin)

插件简介

文本转Word插件 是一款 XpertAI 平台中间件插件，能够将 AI 答复的文本内容或 Markdown 格式内容转换为美观、专业的 Word 文档（.docx），并自动上传到文件服务，返回可直接访问的下载链接。

核心特性

🎨 专业排版：采用蓝色主题配色，标题层次分明，代码块带左侧蓝色装饰条
📊 丰富格式：支持标题、粗体、斜体、代码块、表格、有序/无序列表、引用块、超链接、分割线等
📄 精美文档：包含页眉（文档标题）、页脚（页码）、装饰性顶部色条、标题区域（作者+日期）
📤 自动上传：生成后自动上传到文件服务，返回完整下载 URL
🔧 灵活配置：文件服务地址、上传路径、下载前缀等均可通过配置注入

适用场景

AI 对话中生成报告、文档、方案等需要导出为 Word 的场景
将 Markdown 格式的技术文档转换为可交付的 Word 文件
批量生成合同、通知、周报等格式化文档
需要将 AI 生成内容以文件形式分享给用户

目录结构

text-to-word/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 包配置
├── README.md                    # 本文件
├── src/
│   ├── plugin-code.module.ts    # NestJS 模块（TS 参考）
│   ├── middlewares/
│   │   └── text-to-word.middleware.ts  # 中间件策略（TS 参考）
│   └── schemas/
│       └── config.schema.ts     # 配置 Schema（TS 参考）
├── resources/
│   └── skills/                  # 技能资源目录
└── examples/
    └── request.example.json     # 调用示例

安装方式

通过 XpertAI 平台安装

在 XpertAI 平台的插件市场中搜索 text-to-word 或通过 npm 安装：

插件名称: @timmy_hu/text-to-word
版本: 1.0.0
来源: npm

本地开发

npm install

配置项说明

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | fileServiceBaseUrl | string | ✅ | http://yuhang-test.fpi-inc.site | 文件服务基础地址 | | uploadPath | string | ❌ | /file-base-server/api/v1/sys/upload | 文件上传接口路径 | | downloadPathPrefix | string | ❌ | /file-base-server/api/v1/sys/download/ | 文件下载链接前缀 | | defaultAuthor | string | ❌ | XpertAI | 文档默认作者 | | defaultTitle | string | ❌ | AI生成文档 | 默认文档标题 |

Agent Middleware 工具列表

convert_text_to_word

将文本或 Markdown 内容转换为美观的 Word 文档并上传到文件服务。

入参

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | content | string | ✅ | 要转换的文本或 Markdown 内容 | | title | string | ❌ | 文档标题，显示在文档顶部 | | author | string | ❌ | 文档作者名称 | | format | enum | ❌ | 内容格式：auto（自动检测，默认）、text（纯文本）、markdown | | fileName | string | ❌ | 自定义文件名（不含 .docx 扩展名） |

返回值

{
  "success": true,
  "title": "项目周报",
  "author": "张三",
  "format": "markdown",
  "tokenCount": 12,
  "fileId": "c811a19b27814866ba28cc117ba8aa49",
  "fileName": "项目周报_2026-07-10.docx",
  "downloadUrl": "http://yuhang-test.fpi-inc.site/file-base-server/api/v1/sys/download/c811a19b27814866ba28cc117ba8aa49",
  "fileSize": 25600,
  "fileSizeKB": 25.0,
  "createTime": "2026-07-10 10:15:15.113"
}

支持的 Markdown 语法

标题：# H1 到 ###### H6，H1/H2 带底部装饰线
粗体：**text** 或 __text__
斜体：*text* 或 _text_
粗斜体：***text***
删除线：~~text~~
行内代码：`code`，带粉色背景和等宽字体
代码块：```language ... ```，带语言标签和左侧蓝色装饰条
有序列表：1. item
无序列表：- item、* item、+ item
表格：| col1 | col2 |，带表头高亮和交替行背景色
引用块：> text，带左侧蓝色竖线和浅蓝背景
超链接：[text](url)
分割线：---、***、___

文档设计说明

生成的 Word 文档采用以下专业设计：

配色方案：深蓝主色（#1F3864）、蓝色辅助色（#2E74B5）、蓝色强调色（#4472C4）
字体：正文 Calibri 11pt，代码 Consolas 9.5pt
页眉：右对齐显示文档标题，底部蓝色细线
页脚：居中显示页码（当前页/总页数），顶部蓝色细线
标题区：居中大标题 + 装饰线 + 作者/日期信息
顶部色条：全宽蓝色装饰条
代码块：浅灰背景 + 左侧蓝色粗边框 + 语言标签
表格：蓝色表头 + 交替行背景 + 蓝色边框
引用块：左侧蓝色粗竖线 + 浅蓝背景 + 斜体文字

调用示例

{
  "tool": "convert_text_to_word",
  "input": {
    "content": "# 项目周报\n\n## 本周完成\n\n- 完成了用户模块的 **CRUD** 接口开发\n- 修复了3个 `P0` 级别的Bug\n\n## 数据统计\n\n| 指标 | 本周 | 上周 |\n|------|------|------|\n| 新增用户 | 1,234 | 987 |\n| 活跃用户 | 5,678 | 5,432 |",
    "title": "项目周报 - 2026年第28周",
    "author": "张三",
    "format": "markdown"
  }
}

常见错误和处理方式

| 错误 | 原因 | 处理方式 | |------|------|----------| | 文件上传失败: HTTP 500 | 文件服务内部错误 | 检查文件服务是否正常运行 | | 文件上传失败: HTTP 404 | 上传接口路径错误 | 检查 uploadPath 配置是否正确 | | 响应格式异常 | 文件服务返回非预期格式 | 确认文件服务接口版本兼容 | | ECONNREFUSED | 无法连接文件服务 | 检查 fileServiceBaseUrl 和网络连通性 |

安全注意事项

fileServiceBaseUrl 应使用内网地址，避免暴露到公网
上传的文件名会自动过滤特殊字符（\ / : * ? " < > |）
插件不会存储或缓存上传的文件内容
建议在文件服务端配置访问权限控制

使用方式

在 XpertAI 平台安装本插件
在智能体编排中添加"文本转Word中间件"
配置文件服务地址（fileServiceBaseUrl）
在对话中让 AI 调用 convert_text_to_word 工具
获取返回的 downloadUrl 即可下载 Word 文档

下一步

安装插件后，前往 http://10.161.48.53:3300 的插件管理页面启用插件，然后在智能体编排中添加中间件即可使用。