### 0. 先和大家打个招呼吧 
**你是谁**：一名物流行业的业务运营 / 兼职独立开发者，平时大量接触空运 DEBIT NOTE、发票、提单等 PDF 单据，深知"手工复制粘贴到 Excel"有多折磨人。
**你是怎么用 TRAE 把 Demo 做出来的**：
坦白讲，我本职不是程序员，Python 也是边做边学。最初想做这个工具时，光是"PDF 怎么转成结构化字段"就把我卡了将近一周——`pdfplumber`、`PyMuPDF`、OCR 三条路各有各的坑。**真正让我觉得"原来这么简单"的瞬间有三个：**
1. **让 TRAE 帮我搭架构**：我只说了一句"我要做一个能识别 PDF 物流单据的桌面端工具，支持原生提取和 OCR 双通道"，TRAE 直接给出了 `pdf_smart_reader` 的模块划分建议（`native_extractor` / `ocr_processor` / `pdf_router`），还顺手帮我规划了策略路由的判断逻辑。这一步我原本以为要自己画两天架构图。
2. **让 TRAE 帮我调 LLM 提示词**：字段匹配和 Excel 抽取提示词我反复调了几十个版本，TRAE 不光帮我迭代 prompt，还主动发现了"中文冒号 vs 英文冒号"导致匹配失败这种我自己根本注意不到的细节，最后稳定到几乎 100% 命中率。
3. **让 TRAE 帮我做 UI**：我说"我要 Fluent 风格的窗口，左边是单据列表，右边是字段映射预览"，TRAE 直接用 `qfluentwidgets` 写出了一整套带主题切换、带 loading 动画、带错误兜底的 PySide6 界面——这一步原本是我觉得"搞不定就放弃"的那个坎。
**最大的感受**：TRAE 不是一个"替你写代码的工具"，更像一个"永远在线、从不嫌你问题low的结对编程伙伴"。你说一句人话，它帮你把脑子里的模糊想法变成可运行的工程。
-–
### 1. Demo 简介
**是什么**：一款基于 PySide6 + Fluent Design 的****桌面端 PDF 智能识别系统****（不是 Web 应用，是真正的 Windows/macOS/Linux 原生客户端），支持物流单据、发票、合同等多类型 PDF 的智能字段抽取与 Excel 模板导出。
**面向谁**：
- 物流货代公司的****单据录入员、财务对账员****（核心痛点用户）
- 需要批量处理 PDF 报告的****审计、咨询、运营****人员
- 对 OCR + LLM 混合抽取方案感兴趣的****开发者****
**主要功能**（2-3 个核心）：
#### ① PDF 智能解析（双通道自适应）
系统会先判断 PDF 是"原生文本型"还是"扫描图片型"，自动选择 `pdfplumber` 直抽 / `Tesseract` OCR 路线，对模糊或混合版面自动启用多策略融合。
> 
*（附：主界面截图 + PDF 上传后的解析进度演示）*
#### ② 模板驱动字段匹配 + 抽取
用户上传一次 Excel 模板（如《DEBIT NOTE 录入表》），系统会：
- 用 LLM 智能匹配模板字段 ↔ PDF 字段，输出置信度
- 弹出****匹配预览对话框****，让用户确认/调整映射关系
- 一键批量应用到同类型 PDF
> *（附：字段匹配预览弹窗 + 置信度列表）*
#### ③ 一键导出 Excel + 智能代码生成
抽取完成后直接生成符合模板格式的 `.xlsx`，**附赠"代码生成器"模块**——能根据匹配规则自动生成可复用的 Python 提取代码，下次同类单据零成本复用。
> *（附：导出后的 Excel 截图 + 代码生成器界面）*
-–
### 2. Demo 创作思路
**灵感来源**：
我朋友在一家国际货代公司做财务，每天要处理 50-100 份空运 DEBIT NOTE 发票。每张发票要手动把 30 多个字段（公司名、地址、JOB NO、INV NO、件数、毛重、体积重、空运费金额……）**逐个从 PDF 复制到 Excel**。她告诉我：“做这一行五年，最想砸电脑的就是月底对账那几天。”
**想解决的问题**：
- **痛点 1**：人工录入效率低（一份单据 3-5 分钟，错误率 5%+）
- **痛点 2**：不同货代公司单据版式千差万别，没有通用识别方案
- **痛点 3**：OCR 工具对中英文混排表格识别率差，LLM 又没法直接吃 PDF
**为什么做这个方向**：
物流单据是****结构化但版式不统一**的典型场景——既需要 OCR 处理扫描件，又需要 LLM 理解语义匹配字段。我没有选择做一个"通用 PDF 转 Word"工具，而是**专注在"模板驱动的结构化抽取"这个垂直场景****，把"上传模板 → 自动匹配 → 批量应用"这条链路打通。
**判断和取舍**：
- 
选****桌面端****而非 Web：用户的 PDF 文件含商业机密，不愿上传云端
- 选****PySide6 + Fluent UI****：和 WPS、QQ 的视觉风格一致，降低学习成本
- 选****多模型可插拔****：支持 Qwen / GLM / DeepSeek / Agnes，用户可自配 API
- 
没有做"全自动无人工干预"：保留****匹配预览确认环节****，避免 AI 误识别导致财务事故
-–
### 3. Demo 体验地址（三选一）
由于本 Demo 是 **PySide6 桌面端应用**（非 Web），按官方规则采用：
> ** 方案二：交互式可体验的 HTML 格式文件 + 演示视频**
>
> 1. **产品展示页**：[`创意展示.html`](https://trae-api-cn.mchost.guru/api/ide/v1/text_to_image?prompt=PDF%20agent%20dashboard%20UI%20mockup&image_size=landscape_16_9)（项目根目录下 `创意展示.html`，可直接用浏览器打开查看产品形态与功能介绍）
> 2. **功能演示视频**：[待补充：请将演示视频上传至 B 站/YouTube 后回填链接]
> 3. **源码 & 完整工程**：见项目仓库（包含 `app.py` 主程序、`pdf_smart_reader/` 核心模块、`configs/` 模板库）
> 
*如评审需要本地运行版本，可基于 `requirements.txt` 一键 `pip install -r requirements.txt` + `python app.py` 启动（已支持 Windows / macOS）。*
-–
### 4. TRAE 实践过程
**完整开发流程**（按时间线）：
#### 阶段 1：需求拆解 + 架构设计 
- 向 TRAE 描述业务场景：“物流单据识别 + 模板驱动 + 桌面端”
- TRAE 输出了 `pdf_smart_reader` 三层架构（Router → Extractor → Parser）
- **关键截图**：架构设计对话、`pdf_router.py` 路由策略实现
- **Session ID**：`【.872383174419312:9e3837c21410edb9449790106e1e1990_6a4894d7afe6ab25b3952fa9.6a49b60ba3e66efd8dfbe1b1.6a49b60b30a217605617a854:Trae CN.T(2026/7/5 09:40:27)】`
#### 阶段 2：核心功能实现 — 智能字段匹配 
- 提示词迭代：从 v1 的"自由发挥"到 v27 的"强制匹配规则"
- TRAE 帮我发现了****中文全角冒号 `：` vs 英文半角冒号 `:`****导致 LLM 匹配失败的隐性 Bug
- **关键截图**：字段匹配预览弹窗、置信度排序、用户手动调整
- **Session ID**：`【.872383174419312:9e3837c21410edb9449790106e1e1990_6a4894d7afe6ab25b3952fa9.6a49b60ba3e66efd8dfbe1b1.6a49b60b30a217605617a854:Trae CN.T(2026/7/5 09:40:27)】`
#### 阶段 3：UI 实现 — Fluent 风格界面 
- 一句话需求：“我要像 WPS 那种现代化界面，左侧单据列表 + 右侧字段映射”
- TRAE 用了 `qfluentwidgets` 直接生成完整 PySide6 窗口代码
- **关键截图**：主界面、主题切换、loading 动画、错误提示 InfoBar
- **Session ID**：`【.872383174419312:9e3837c21410edb9449790106e1e1990_6a4894d7afe6ab25b3952fa9.6a49b60ba3e66efd8dfbe1b1.6a49b60b30a217605617a854:Trae CN.T(2026/7/5 09:40:27)】`
#### 阶段 4：批量处理 + 代码生成器 
- 痛点：“同一类型单据下次还要重跑，能不能自动生成提取代码？”
- TRAE 帮我设计了 `code_generator.py`，根据匹配规则自动生成可复用 Python 脚本
- **关键截图**：批量队列、自动生成的提取代码片段
- **Session ID**：`【.872383174419312:9e3837c21410edb9449790106e1e1990_6a4894d7afe6ab25b3952fa9.6a49b60ba3e66efd8dfbe1b1.6a49b60b30a217605617a854:Trae CN.T(2026/7/5 09:40:27)】`
### 5. 对应的报名审核通过的帖子链接
> **报名审核通过帖**：`【https://forum.trae.cn/t/topic/45423】`
>
> 报名赛道：**学习工作**
> 报名时间：`【2026-06-25 09:40:27】`
*以上为本项目【PDF 智能体】的初赛参赛帖，真诚感谢评审老师的时间 
如有疑问欢迎在评论区交流~*
pdf智能体开发.zip (729.3 KB)