📝 技术博客：构建 Word 文档分章节解析与大模型批量审核工具

作者：Eddygit
日期：2026-08-29
项目：方案审核智能体工具（Solution Review Agent）

一、技术路线与架构

1.1 需求分析

核心需求很明确：用户有一份 Word 格式的方案文档（可能几十页），希望工具能自动按章节拆分，然后把每个章节分别发给大模型 API 进行审核，最后汇总展示审核结果。

这其实是一个典型的"文档 → 分片 → 批量推理 → 汇总"流水线问题。

1.2 技术选型

1.3 架构设计

┌─────────────────────────────────────────────────────┐
│                    浏览器（前端）                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ 文件上传  │  │ API配置   │  │ 审核结果展示      │   │
│  │ 拖拽区    │  │ Base URL  │  │ 章节折叠 + 雷达图 │   │
│  └────┬─────┘  └────┬─────┘  └────────▲─────────┘   │
└───────┼──────────────┼─────────────────┼────────────┘
        │              │                 │
        ▼              ▼                 │
┌─────────────────────────────────────────┴───────────┐
│                  Flask 后端                          │
│  ┌─────────────┐    ┌──────────────────────────┐    │
│  │ /api/upload  │    │ /api/review              │    │
│  │ 接收 .docx   │    │ 接收章节 + API配置        │    │
│  │ python-docx  │    │ ThreadPoolExecutor 并发   │    │
│  │ 按章节拆分   │    │ 调用 OpenAI 兼容 API     │    │
│  └─────────────┘    └──────────────────────────┘    │
└─────────────────────────────────────────────────────┘

1.4 章节拆分策略

这是整个工具最关键的一步。Word 文档的章节标记有两种主要方式：

1. 样式标记：段落使用 Heading 1、Heading 2 样式（规范的文档通常用这种方式）
2. 文本模式：段落文本以"第一章"、“第2节”、"第三部分"等开头（不规范但常见）

工具同时检测这两种模式，任一命中即认为是章节边界。正则表达式：

CHAPTER_PATTERN = re.compile(r'^第[一二三四五六七八九十百千万零〇\d]+[章节部分篇条]')

1.5 并发审核设计

使用 ThreadPoolExecutor 并发调用大模型 API，每个章节一个独立任务：

with ThreadPoolExecutor(max_workers=5) as executor:
    futures = {
        executor.submit(call_llm_api, chapter, config): chapter
        for chapter in chapters
    }
    for future in as_completed(futures):
        result = future.result()
        # 实时推送进度到前端

max_workers=5 是一个平衡值——太快会触发 API 限流，太慢用户等待时间长。

二、技术心得

2.1 python-docx 的坑

python-docx 的 API 设计比较直觉，但有几个细节值得注意：

• 样式名不统一：中文 Word 文档的标题样式名可能是"标题 1"（有空格）、“Heading 1”、甚至自定义名称。必须做模糊匹配。
• 空段落：文档中常有空段落，解析时需要 .strip() 后判断是否为空，否则会产生大量"空章节"。
• 表格内文字：python-docx 默认只遍历 document.paragraphs，表格内的文字不会被包含。如果方案中有表格内容，需要额外遍历 document.tables。

2.2 大模型 API 的错误处理

实际调用大模型 API 时会遇到各种异常：

• 超时：某些章节内容很长，API 响应慢，需要设置合理的 timeout
• 限流（429）：并发太高会被限流，需要重试机制
• 格式错误：API 返回的 JSON 可能不符合预期结构，需要防御性解析

工具中对每个章节的审核都做了 try-catch 包裹，单个章节失败不影响其他章节的审核结果。

2.3 前端实时进度

审核过程可能持续几十秒，用户需要看到进度。采用轮询方式：

1. 前端发起审核请求
2. 后端在审核每个章节完成后，将进度写入共享状态
3. 前端定时轮询 /api/progress 获取当前进度
4. 全部完成后，前端拉取最终结果

相比 WebSocket，轮询实现更简单，对于这种短时任务完全够用。

2.4 DevSpace 端口预览

华为云 DevSpace 开发者工作空间自带端口预览功能，格式为：

https://<PORT>-<CONTAINER_ID>.workspace.developer.huaweicloud.com/

只要服务监听 0.0.0.0:PORT，就能通过这个 URL 直接访问，无需额外配置隧道。这比 DevBridge 隧道更简单，适合开发预览场景。

三、实战经验

3.1 CodeArts 代码生成

本项目通过 CodeArts ACP（Agent Client Protocol）协议让 AI 智能体生成代码。几个实战经验：

1. 提示词要具体：明确指定技术栈、文件结构、端口号、功能点，AI 才能一次生成可用代码
2. 环境差异：沙箱中 Python 版本和 pip 路径可能与预期不同，需要让 AI 先检测环境再安装依赖
3. 信任结果但验证：AI 生成的代码需要验证服务是否真的启动了、页面是否能访问

3.2 GitCode 推送

GitCode 使用 Gitea 内核，API 与 Gitea 兼容。推送代码时的几个要点：

• Token 认证使用 URL 嵌入格式：https://oauth2:<token>@gitcode.com/...
• auto_init=true 创建的仓库有初始 commit，本地代码需要 --allow-unrelated-histories 合并
• 合并冲突时用 git checkout --ours . 保留本地版本

3.3 多维度评分设计

审核不是简单的"好/坏"判断，而是多维度评分。设计时考虑了：

• 权重分配：完整性 25%、逻辑性 25%、可行性 20%、风险性 15%、创新性 15%
• 可视化：雷达图直观展示各维度得分
• 可配置：用户可以在管理后台自定义维度和权重

四、存在问题

4.1 文档解析的局限性

• PDF 解析：当前对 PDF 的解析依赖简单文本提取，复杂排版的 PDF 可能丢失结构信息
• 表格内容：Word 文档中的表格内容未被纳入章节解析
• 嵌套标题：Heading 3 及更深层级的标题未被识别为章节边界

4.2 大模型调用的不确定性

• 结果格式：大模型返回的审核意见格式不统一，有时是 JSON，有时是纯文本，解析不够鲁棒
• 上下文长度：超长章节可能超出模型的上下文窗口限制，目前未做自动分片
• 成本控制：没有对 API 调用次数和 token 消耗做统计和限制

4.3 安全性

• 默认密码：admin/admin123 是硬编码的，生产环境应改为环境变量或数据库存储
• 文件上传：虽然限制了文件类型和大小，但未对文件内容做安全扫描
• API Key 存储：前端配置的 API Key 通过 HTTP 传输，应使用 HTTPS

4.4 用户体验

• 审核等待：大量章节审核时等待时间较长，缺乏更细粒度的实时反馈
• 移动端适配：当前 UI 主要面向桌面端，移动端体验未优化
• 导出格式：仅支持文本导出，缺少 PDF/Word 格式的审核报告

五、优化空间

5.1 短期优化

5.2 中期优化

5.3 长期方向

• RAG 增强：将历史审核结果构建为知识库，新文档审核时参考历史经验
• 自定义审核技能：用户可以编写 Python 插件定义自己的审核逻辑
• 协作审核：多人同时对同一文档的不同章节进行人工+AI 协同审核
• 审核模型微调：基于历史审核数据微调专用审核模型

六、总结

这个工具的核心价值在于：把"人工逐章阅读方案 → 人工写审核意见"的重复劳动，自动化为"上传文档 → AI 批量审核 → 可视化报告"的流水线。

技术上的关键决策是：

1. 用 python-docx 做章节拆分（而非整文档丢给大模型），既节省 token 又能精确定位问题
2. 用线程池并发调用 API，大幅缩短审核时间
3. 多维度评分 + 雷达图可视化，让审核结果一目了然

整体而言，这是一个"小而美"的工具——功能聚焦、技术栈简洁、部署方便。后续优化方向主要是鲁棒性（错误处理、长文档支持）和智能化（RAG、多模型对比）。