【学习工作赛道】DocDiff —— 文档改了哪里，一眼看清
标签：学习工作
赛道：TRAE AI 创造力大赛 · 学习工作赛道
作品形态：前后端分离 Web 应用（FastAPI + Vue 3）
体验方式：下载项目包，运行 start.ps1 一键启动，浏览器自动打开
一、项目基本信息
| 项目字段 | 内容 |
|---|---|
| 作品名称 | DocDiff —— 文档改了哪里，一眼看清 |
| 项目类型 | Web 实用工具 / 文档智能比对 |
| 一句话简介 | 上传两个文档（PDF/Word），自动高亮差异并标注风险等级，把 30 分钟的人工比对压缩到 1 分钟 |
| 技术栈 | Vue 3 + Vite / FastAPI + pdfplumber + python-docx / difflib + DeepSeek API |
| 体验方式 | 下载项目包，运行 start.ps1 一键启动 |
二、Demo 简介
2.1 是什么
DocDiff 是一个文档智能比对工具。用户上传原始文档和修改后文档，系统自动：
- 提取文本内容（支持 PDF 文字版和 Word .docx）
- 用 difflib 确定性算法逐行比对，红绿高亮差异
- 用规则 + AI 混合架构对每处变更进行风险分级（高/中/低）
- 生成自然语言变更摘要，概括主要变更内容
2.2 面向谁
-
法务/合同审核人员：比对合同修改稿，快速定位金额、期限、违约责任等关键条款变更
-
采购人员：比对采购方案版本差异，确认数量、价格、交货条款变化
-
项目管理人员：比对需求文档、方案文档的迭代版本
-
任何需要审核文档修改的人：比邮件来回发文档省心，比肉眼比对靠谱
2.3 主要功能
- 双文档上传 —— 支持拖拽上传 PDF（文字版）和 Word（.docx），实时显示文件信息
- 红绿高亮对比 —— 新增内容绿色高亮，删除内容红色高亮，未变内容正常显示
- AI 风险分级 —— 每处变更自动标注风险等级（高/中/低），高风险用红色色条醒目标记
- AI 变更摘要 —— 自然语言概括本次修改的主要内容，一眼掌握变更全貌
- 极简文档风界面 —— 衬线字体 + 等宽字体 + 纸墨配色，像翻阅一本精心排版的书籍
文件上传界面（双区域拖拽上传）
差异对比结果（红绿高亮 + 风险标记 + AI 摘要）
复杂合同比对场景（表格、多级标题的处理效果）
三、Demo 创作思路
3.1 灵感来源
在工作和学习中，经常遇到"文档改了哪里"的问题：合同对方发来修改稿，采购方案迭代了新版本，需求文档做了调整。传统做法是逐段肉眼比对，一份 10 页合同要花 30 分钟，还容易漏看关键条款。现有工具要么是纯文本 diff（不懂语义），要么价格昂贵。
3.2 想解决的痛点
| # | 痛点 | 真实体感 |
|---|---|---|
| 1 | 人工比对耗时 | 10 页合同逐段对比需要 30 分钟，效率极低 |
| 2 | 容易漏看关键变更 | 金额从 80 万改到 120 万、违约金从万分之五改到万分之三，藏在长段落里很容易忽略 |
| 3 | 纯 diff 工具不懂语义 | 命令行 diff 只能告诉你"这里改了"，但不告诉你"这处改动重不重要" |
| 4 | AI 工具有幻觉风险 | 直接让 AI 比对文档，它可能编造差异或漏掉差异，不可信 |
3.3 为什么做这个方向
-
赛道契合度高：学习工作赛道的核心是"效率提升"，文档比对是典型的重复性高、价值明确的工作场景
-
痛点真实：自己审合同时亲身经历过漏看违约金条款的教训
-
AI 价值明确：不是为用 AI 而用 AI，而是解决"diff 只能发现差异、不能理解差异"的真实问题
-
可演示性强：上传两个文档即可体验，效果直观
四、核心功能与创新亮点
4.1 反幻觉五层架构（核心创新）
这是本项目最本质的设计——不是让 AI 比对文档，而是让 AI 理解差异。
| 层级 | 职责 | 技术 | 是否涉及 AI |
|---|---|---|---|
| 第一层 | 文本提取 | pdfplumber / python-docx | 否，开源库确定性提取 |
| 第二层 | 差异发现 | difflib.ndiff | 否，100%确定性算法 |
| 第三层 | 风险分级 | 规则匹配 + DeepSeek API | 规则确定等级，AI 优化原因 |
| 第四层 | 结果校验 | 覆盖校验 + 降级机制 | 否，规则兜底 |
| 第五层 | 产品策略 | 原始 diff 始终可见 | 否，AI 失败不影响核心功能 |
核心原则：difflib 负责"发现差异"（确定性，100%准确），AI 只负责"理解差异"（风险分级 + 摘要，辅助参考）。AI 任何环节失败，产品降级为纯 diff，核心功能不受影响。
4.2 规则预筛 + AI 复核混合架构（核心创新）
经过纯规则和纯 AI 两种方案的实测对比，最终采用混合架构：
| 维度 | 纯规则 | 纯 AI（思考模式） | 混合模式（最终方案） |
|---|---|---|---|
| 耗时 | <1 秒 | 69 秒 | 17.7 秒 |
| 金额变更识别 | 正确 | 误判为"排版调整" | 正确 |
| 风险原因质量 | “涉及比例变更” | 有时有偏差 | “违约金从万分之五降至万分之三” |
| 摘要质量 | 模板拼接 | 自然语言 | 自然语言 |
设计要点：
-
规则确定 risk_level：金额、比例、日期等数字类变更用正则匹配，确定性高，不会误判
-
AI 只优化 risk_reason：让 AI 生成更具体的风险原因描述，不改风险等级
-
关闭思考模式：
extra_body={"thinking": {"type": "disabled"}}，耗时从 69 秒降到 17.7 秒 -
分批处理：大文档每批最多 50 行，避免 token 爆炸
4.3 极简文档风界面设计
界面采用"极简文档风（Ink & Paper）"设计语言：
-
配色：墨黑
#1a1a1a+ 纸白#fafaf7+ 朱红删除标记 + 翠绿新增标记 -
字体：衬线字体 Noto Serif SC 做标题，等宽字体 JetBrains Mono 做 diff 内容，无衬线 Noto Sans SC 做辅助文本
-
排版：大量留白，克制装饰，像法律文书一样严谨
-
风险标记：左侧 3px 色条 + 行内 6px 圆点 + 右侧原因标签，醒目但不喧宾夺主
4.4 完整的降级机制
| 场景 | 降级行为 |
|---|---|
| 未配置 DeepSeek API Key | 纯规则匹配，风险分级和摘要均可用 |
| API 调用超时/失败 | 保留规则结果，风险原因用规则兜底 |
| AI 返回空内容 | 保留规则结果 |
| AI 返回 JSON 解析失败 | 保留规则结果 |
| API 返回未覆盖的行 | 用规则补齐（覆盖校验） |
五、技术架构与选型
5.1 技术栈
| 层级 | 选型 | 说明 |
|---|---|---|
| 前端核心 | Vue 3 + Vite | 组合式 API，开发体验好 |
| 后端框架 | FastAPI | 异步高性能，自带 OpenAPI 文档 |
| 文档提取 | pdfplumber + python-docx | PDF 文字版 + Word .docx |
| 比对引擎 | difflib.ndiff | Python 标准库，确定性算法 |
| AI 增强 | DeepSeek API（deepseek-v4-flash） | OpenAI 兼容格式，成本低 |
| 密钥管理 | python-dotenv | 环境变量注入，不硬编码 |
5.2 项目结构
docdiff/
start.ps1 一键启动脚本
README.md 使用说明
.gitignore 忽略 .env / node_modules 等
backend/
main.py FastAPI 入口，API 编排 + 文件校验
extractor.py 文档文本提取（PDF + Word）
differ.py difflib 差异比对（纯算法，无副作用）
ai_analyzer.py AI 风险分析（规则预筛 + AI 复核 + 降级）
requirements.txt Python 依赖
.env.example 环境变量模板
frontend/
src/
App.vue 主应用（状态管理 + API 调用）
components/
FileUpload.vue 文件上传（拖拽 + 校验）
DiffView.vue 差异展示（高亮 + 风险标记 + 摘要）
style.css 全局样式（极简文档风 CSS 变量）
vite.config.js
package.json
screenshots/ 开发过程截图
test_*.docx 测试文档
5.3 关键技术实现
5.3.1 反幻觉架构：差异发现与风险理解分离
# main.py 核心流程
diff_result = diff_texts(text1, text2) # 第二层：difflib 确定性比对
stats = get_diff_stats(diff_result) # 统计
diff_result = batch_analyze_risk(diff_result) # 第三层：规则预筛 + AI 复核
risk_stats = get_risk_stats(diff_result) # 风险统计
summary = generate_summary(diff_result, stats) # AI 摘要
5.3.2 混合 AI：规则确定等级，AI 优化原因
# ai_analyzer.py 核心逻辑
def batch_analyze_risk(diff_result):
# 第一步：规则预筛（快速、确定性，确定 risk_level）
_rule_batch_analyze(diff_result)
# 第二步：收集 high/medium 行，调 AI 复核 risk_reason
risk_lines = [(i, item["type"], item["content"], item["risk_level"])
for i, item in enumerate(diff_result)
if item["type"] != "unchanged"
and item.get("risk_level") in ("high", "medium")]
reason_map = _call_deepseek_refine_reason(risk_lines)
# 用 AI 结果覆盖规则的 risk_reason（不改变 risk_level）
if reason_map:
for idx, reason in reason_map.items():
diff_result[idx]["risk_reason"] = reason
return diff_result
5.3.3 降级机制：AI 失败时保留规则结果
def _call_deepseek_refine_reason(risk_lines):
client = _get_client()
if client is None:
return None # 无 API Key，返回 None，调用方保留规则结果
try:
response = client.chat.completions.create(...)
return reason_map
except Exception as e:
logger.warning(f"DeepSeek 调用失败，保留规则结果: {e}")
return None # 失败返回 None，调用方保留规则结果
六、TRAE AI 赋能开发全纪实
本项目全程使用 TRAE Work 完成，从需求梳理到测试验证，TRAE AI 在每个关键节点都发挥了决定性作用。
6.1 关键任务 Session ID
以下 Session ID 可在 TRAE IDE 中验证。
| 序号 | 任务描述 | Session ID | 时间 |
|---|---|---|---|
| 1 | 需求梳理：分析创意文档，确认应用开发的基础内容（产品定位、目标用户、功能优先级） | 6a4f546727f5aa0c83d0b0e0 |
2026/7/9 15:57 |
| 2 | 技术方案：查询比赛要求，确认技术栈（Vue + FastAPI）和提交规范 | 6a4f55a327f5aa0c83d0b12c |
2026/7/9 16:02 |
| 3 | MVP 开发：后端（extractor + differ + main）+ 前端（FileUpload + DiffView）编码与联调 | 6a4f56f827f5aa0c83d0b15d |
2026/7/9 16:08 |
| 4 | UI 美化：推荐 4 种设计风格，选定"极简文档风"，重写全部前端样式 | 6a4f639f0f48530dd560f467 |
2026/7/9 17:02 |
| 5 | 全面测试：14 项测试覆盖正常比对、边界情况、复杂格式，全部通过 | 6a4f66fb0f48530dd560f4fa |
2026/7/9 17:16 |
6.2 开发关键步骤截图
截图 1：需求梳理 —— AI 分析创意文档，输出结构化需求
对应步骤：项目启动阶段，使用 ai-dev-assistant 技能分析创意文档，AI 输出产品定位、目标用户、功能优先级等结构化需求。
截图内容：TRAE Work 中 AI 输出的需求摘要确认表，包含产品名称（DocDiff）、产品形态（Web 应用）、赛道（学习工作）、核心价值（30 分钟压缩到 1 分钟）。
截图 2：技术方案 —— AI 查询比赛要求，确认技术栈
对应步骤：技术方案阶段，AI 查询大赛官方要求，输出要求汇总表，确认开发工具（TRAE IDE/Work）、过程证明（3+ Session ID + 3+ 截图）、体验方式、截止日期等关键信息。
截图内容：TRAE Work 中 AI 输出的大赛要求汇总表。
截图 3：MVP 开发 —— 后端+前端编码完成，测试通过
对应步骤：MVP 开发阶段，后端（FastAPI + pdfplumber + python-docx + difflib）和前端（Vue 3 + Vite）编码完成，AI 输出状态总结，显示当前阶段 3/6 编码 → 4/6 测试，后端服务、文档提取、差异比对三个模块全部通过。
截图内容：TRAE Work 中 AI 输出的 MVP 完成状态报告。
截图 4：UI 美化 —— AI 推荐 4 种设计风格，选定极简文档风
对应步骤：UI 美化阶段，调用 frontend-design 技能，AI 推荐 4 种设计风格（极简文档风、科技感深色风、杂志编辑风、温暖纸质感），最终选定"极简文档风（Ink & Paper）"，AI 输出配色方案（墨黑+纸白+朱红）、字体选择（Noto Serif SC + JetBrains Mono）、设计特点。
截图内容：TRAE Work 中 AI 输出的"风格一：极简文档风"设计推荐。
截图 5：全面测试 —— 14 项测试全部通过
对应步骤：测试验证阶段，AI 生成 14 项测试用例，覆盖健康检查、正常比对、不支持格式、相同文档、空文档、5+ 页长文档、200 行大文档、缺少文件参数、差异准确性（数量/价格/保修期/付款条件/违约金/争议解决）等场景，全部通过。
截图内容：TRAE Work 中 AI 输出的测试报告，14 项测试通过，0 失败。
6.3 TRAE 在关键节点的赋能
6.3.1 反幻觉架构设计
最初考虑直接让 AI 比对两个文档，但 TRAE AI 帮助分析了 AI 幻觉的风险，最终设计了五层反幻觉架构：difflib 负责确定性差异发现（100%准确），AI 只负责理解差异（风险分级 + 摘要），AI 失败时降级为纯 diff。这个设计成为产品的核心卖点。
6.3.2 混合 AI 架构优化
纯 AI 方案测试时发现两个问题：一是耗时 69 秒（默认开了思考模式），二是金额变更被误判为"排版调整"。TRAE AI 帮助分析了根因，最终设计了"规则预筛确定等级 + AI 只优化原因"的混合架构，耗时降到 17.7 秒，准确性问题消除。
6.3.3 DeepSeek API 接入
TRAE AI 查阅了 DeepSeek 官方文档，确认了 API 格式（OpenAI 兼容）、模型选择（deepseek-v4-flash，成本最低）、JSON Output 模式用法、思考模式开关（extra_body={"thinking": {"type": "disabled"}}），避免了瞎猜接口。
6.3.4 一键启动脚本
部署阶段遇到多个环境兼容问题：PowerShell 5 不支持 ?? 运算符、npm 是批处理文件需用 cmd.exe /c 调用、中文编码导致脚本语法错误、TRAE 内置 Python 干扰路径检测。TRAE AI 逐一定一排查修复，最终实现真正的一键启动。
七、Demo 体验指南
7.1 运行环境
-
Python 3.10+（后端运行环境）
-
Node.js 18+（前端构建环境）
-
浏览器：Chrome / Edge / Firefox / Safari
7.2 快速上手（评委第一体验路径）
-
第一步：解压项目包，进入
docdiff目录 -
第二步：右键
start.ps1→ “使用 PowerShell 运行” -
第三步：脚本自动安装依赖、启动前后端服务、打开浏览器
-
第四步：在页面左侧上传"原始文档"，右侧上传"修改后文档"（可用项目自带的测试文档）
-
第五步：点击"开始比对"，等待几秒钟
-
第六步：查看结果——顶部 AI 摘要概括主要变更，下方红绿高亮显示每处差异，左侧色条标记风险等级
7.3 体验验证清单
评委可对照以下清单验证 demo：
-
一键启动脚本能正常启动前后端并打开浏览器
-
上传两个 .docx 文档能正常比对
-
差异以红绿高亮显示，新增绿色、删除红色
-
AI 摘要正确概括了主要变更内容
-
风险分级标记正确（高风险红色色条、中风险橙色、低风险绿色）
-
风险原因描述具体（如"违约金从万分之五降至万分之三"）
-
上传不支持的格式（如 .txt）能正确提示错误
-
上传相同文档显示"未发现差异"
7.4 AI 功能配置（可选）
默认使用规则匹配进行风险分级，无需任何配置即可使用。
如需启用 DeepSeek AI 增强风险原因和变更摘要：
-
在
backend/目录下创建.env文件 -
填入：
DEEPSEEK_API_KEY=sk-你的密钥 -
重启后端服务
API Key 申请：https://platform.deepseek.com/api_keys
未配置 API Key 时自动降级为规则匹配，核心功能不受影响。
八、测试文档说明
项目附带测试文档，可直接体验：
| 文档 | 说明 | 包含的变更 |
|---|---|---|
test_original.docx / test_modified.docx |
基础合同比对 | 数量、价格、保修期、付款条件、违约金、争议解决 |
test_complex_original.docx / test_complex_modified.docx |
复杂格式合同（含表格、多级标题、编号列表） | 14 处设计变更：金额、期限、违约金、知识产权、争议解决等 |
本项目全程使用 TRAE Work 开发，从需求梳理到部署提交，TRAE AI 在每个关键节点都发挥了决定性作用。
DocDiff_final.zip (619.4 KB)