AI Agent 智能体实战开源项目：Word 文档格式规范化智能体 DocFmtAgent（LLM 自主决策 + Skills 架构 + SSE 思维链）

一个用「真 Agent 范式」解决真实痛点的全栈开源项目：LLM 自主规划、调用 9 个技能、边思考边流式输出思维链，把一份排版混乱的 Word 文档从 52 个格式问题一键修到 0。

1. 前言：一个所有打工人都懂的痛

做软件交付、写标书、交课设的同学一定经历过这个场景：内容终于写完了，甲方/导师甩来一份《材料文档格式要求》——正文宋体小四、行距 1.5 倍、一级标题黑体三号居中、图表要有编号和题注、页边距上下 2.54……然后你开始一页一页手动改格式，改完还漏了十几处，返工三遍。

这类活有三个特点：规则明确、机械重复、容易漏改——完美适合交给程序。但传统方案（Word 宏 / VBA / 模板套用）有个致命缺陷：格式规则换个单位就全部作废，而且中文字体（eastAsia）、精确行距（twips）这些细节，宏脚本很难写对。

所以我做了 DocFmtAgent（文档格式规范化智能体）：一个基于 LLM Agent 自主决策 + Skills 技能架构 的 Word(.docx) 格式规范化系统。它不是"调一次 API 改个格式"的玩具，而是一个完整的 Agent 工程：

• 真·Agent 范式：LLM 在循环里自主「规划 → 调工具 → 看结果 → 反思」，不是写死的流水线；
• 检测可量化：实测一份演示用的操作手册文档，一次性检出 52 个格式问题（高 14 / 中 28 / 低 10），逐条列明段落位置与期望值；
• 修复可验证：一键修复后复检 0 问题，内容、图片、表格原样保留，只动格式不动文字；
• 核心创新·示例学习：给 1~N 份金标准样本，Agent 自己提炼出整套 19 角色格式规则，生成可对话微调的个人模板——换一家单位的规范，学习一次就能用。

项目已开源（MIT 协议，可自由商用二次开发），开源地址见小结。

2. 项目介绍与技术栈

2.1 三大核心能力

能力	说明
🔍 智能检测	对照格式规则模板逐项检测：字体/字号/对齐/缩进/行距/页面设置，输出按严重度分级的问题清单
🔧 一键修正	按规则自动修复并生成新文档 + 修改记录；修复后自动复检，实测 52 → 0 问题全量消除
🧠 示例学习 ⭐	金标准样本 → 自动提炼 19 角色格式规则（三层优先级 + 众数/冲突识别），学习过程思维链全程可视

2.2 技术栈

层	技术
智能体运行时	Anthropic 协议 tool_use + thinking（兼容 Claude / GLM 等模型）
核心检测/修订调度	Claude Code + claude-agent-sdk（可选启用，驱动核心 DOCX 工作流）
文档底座	python-docx + lxml（中文字体 eastAsia、行距 twips 精确读写）
后端	FastAPI + Uvicorn（SSE 流式推送）
前端	Vue 3 + Vite（三大工作区）
持久化	MySQL / PyMySQL（修订记录 + 学习历史，未配置自动降级）

选型上有一处值得说：没有用 MarkItDown / docling 这类"docx 转 Markdown"方案。转 Markdown 会把字体、行距、缩进这些格式细节全部丢掉，而格式规范化恰恰要精确操作这些细节，所以文档层直接用 python-docx + lxml 读写 OOXML，中文字体走 w:rFonts/w:eastAsia 节点。

3. 系统架构：skills 是唯一能力底座

整个系统一条主线：前端 → FastAPI → LLM Agent → skill_runtime → skills → 确定性工具层。

这里面最重要的架构决策是：9 个 skill 是前端和 Agent 共用的唯一能力底座。

skills/
├── detect_format/          # 检测入口（委托 format_extraction）
├── fix_format/             # 修复入口（委托 style_application）
├── xml_processing/         # DOCX 解包/封包/校验（OOXML 原子工具）
├── format_extraction/      # 格式提取工作流
├── style_application/      # 样式应用工作流
├── evaluate_format/        # 修复后质量评估/验收
├── learn_from_samples/     # 示例学习 ⭐
├── manage_template/        # 模板查看/列表/修订历史
└── update_template/        # 模板微调（带范围守护）

每个 skill 是一个独立目录（SKILL.md 声明 + scripts/run.py 实现 def run(params) -> dict），由 skill_runtime 用 importlib 自动发现、统一分发：前端点按钮走 call()，LLM Agent 拿到的 tools（as_tools()）也是同一套。加一个新能力 = 在 skills/ 下加一个目录，前端和 Agent 同时可用，不存在第二条路径。

这样设计的好处一句话说清：LLM 负责"决策"，skills 负责"执行"。Agent 的价值在规划与反思，而改字体、读写 XML 这类确定性操作必须落在可测试、可回归的工具层——这也是 Agent 工程里防"模型幻觉改坏文档"的关键护栏。

4. Agent 工作机制：看得见的思考循环

以「示例学习」为例：前端发起 /api/learn/stream 后，Agent 进入 tool_use 循环——先 thinking 规划提取策略，再 tool_use 调用 learn_from_samples，拿到 tool_result 后判断规则是否完整，不完整就继续思考下一轮。每个思考步通过 SSE 实时推回前端，所以用户看到的不是黑盒转圈几十秒，而是思维链逐条增长：

上图是一次真实学习过程的截图：「步骤 1 thinking」里 Agent 分析两份样本文档的角色覆盖情况，「步骤 2 tool_use」发起 learn_from_samples 调用，「步骤 3 tool_result」返回 19 个角色的规则——三步思维链完整可见，随后状态栏提示"样本规则已提炼(19 个角色)，正在撰写分析报告…"。

两个工程细节：

1. thinking 块不入历史。早期把 thinking 写回对话历史后，模型会反复重放相同推理、重复调工具；现在每轮入历史前先剥离 thinking 块，循环稳定收敛。
2. SSE 而非 WebSocket。思维链是服务端单向推送，SSE（StreamingResponse + text/event-stream）够用且断线重连语义简单，前端 getReader() 逐行解析即可。

5. 核心创新：示例学习与三层优先级提取

「换一家单位就废」是传统格式脚本的最大痛点。示例学习的思路是：与其手写规则，不如给 Agent 看几份排好版的"金标准"，让它自己把规则学出来。

提取时的核心是三层优先级：

1. P1 文字描述：文档里明文写的格式要求（如"正文小四宋体"）优先级最高；
2. P2 批注：审阅批注中的格式指示次之；
3. P3 XML 众数统计：什么都没写时，对同角色段落（比如全部一级标题）统计字体/字号/行距的众数——多数怎么排，规则就是什么。

多样本之间出现分歧时做冲突识别与标注，最后汇总成 19 个段落角色（各级标题/正文/图题/表题/目录/摘要……）加文档级配置（页面、页码、编号、图表引用方式）的完整规则集。

学习完成后，Agent 还会给出决策点让你确认——比如英文字体是跟随样本还是套用常用映射、图表引用方式取"上方编号"还是"下方编号"。确认后一键保存为个人模板，之后所有检测/修复都能用这套学来的规则。

学习历史落在 MySQL（learn_history 表），刷新页面、换台设备，历史和模板都在：

而 MySQL 是全容错设计：没配数据库时相关功能静默降级，检测/修复/学习主流程完全不受影响——部署门槛从"必须装 MySQL"降到了"可选装"。

6. 功能演示：52 个问题到 0 的全流程

6.1 上传与检测

进入「格式修订」工作区，上传待检文档，选择格式模板（内置 8 类预置：需求规格/概要设计/详细设计/用户手册/测试报告/招投标文件/通用交付材料/公文行文），点击一键检测：

检测由 Claude Code 驱动核心 DOCX 工作流执行，状态实时可见。完成后输出问题全景：

实测演示文档：52 个格式问题全量检出——高严重度 14 / 中 28 / 低 10，每条都标明角色、期望值与实际值（比如"正文行距期望 1.5 倍，实际单倍"），右侧还能看到 Agent 的结构分析过程。

6.2 一键修复与复检

一键修复后自动复检：52 → 0，格式问题 100% 消除，修正后的文档可直接下载。左侧修订历史按批次留痕（哪次修的、改了多少处），右下是逐项修改明细。

这里有个容易被问的点：只改格式，不改内容。修复链路里专门有内容保全校验（preserve_media_tables + postcheck），图片、表格、文字内容在修复前后做一致性比对，防止"格式修好了、内容修没了"。

7. 模板管理：8 类预置 + 对话式微调

预置模板开箱即用，点开任意一个就是完整的 19 角色规则视图：

个人模板（示例学习产出的）支持自然语言对话微调——直接说"正文字号改小四"、“页码从第 3 页开始编号”，Agent 调 update_template 完成修改。这里做了范围守护：你说"把所有标题改成红色"这类超出格式规则边界的指令会被拒绝并提示，防止微调把模板改崩。每次微调的字段级变更（role.field: old → new）都写入 template_revisions 表，随时可追溯。

8. 快速上手

三步跑起来（Python ≥ 3.10 + Node.js，MySQL 可选）：

# 1. 配置凭证：填 LLM 的 token/base_url/model（Anthropic 协议，GLM 等均可）
cp .env.example .env

# 2. 启动后端（端口 8000）
pip install -r requirements.txt
uvicorn src.agent_runtime.server:app --port 8000

# 3. 启动前端（端口 5173）
cd frontend && npm install && npm run dev

访问 http://127.0.0.1:5173，上传一份 docx 即可体验检测/修复；丢两份格式规范的样本进去就能跑示例学习。也可以不走界面直接调 skill（python -c "from src.skill_runtime import call; ..."）或用 Agent CLI（python -m src.agent_runtime.agent "..."），方便集成进已有流水线。

9. 小结

这个项目把 Agent 工程里最值得练的几件事都真实落地了：tool_use 决策循环、thinking 与 SSE 思维链流式、skills 插件化能力底座、示例学习这种"从样本归纳规则"的进阶玩法、外加确定性工具层兜底和持久化容错设计。

几类同学可以各取所需：

• 想入门 AI Agent 开发的同学：它比"又一个 chatbot"多了完整的工程化细节——工具 schema 设计、思维链剥离、循环收敛、容错降级，每一处都是面试可以聊的点；
• 做交付/标书/论文格式工作的同学：预置 8 类模板开箱即用，遇到自家规范就丢样本让它学一份个人模板；
• 想二次开发的同学：skills 加目录即插即用，检测/修复/学习每个能力都能单独 call()，方便嵌进已有的文档流水线。

开源地址（MIT 协议）：

damengxiangjiaZTY/docfmt-agent - Gitee

完整资源已整理上传（含全部源码、保姆级部署文档、二次开发指南与 19 角色格式字典说明）：

AI Agent智能体实战项目：Word文档格式规范化智能体DocFmtAgent完整源码+部署文档+二次开发指南

如果在实现类似系统时遇到问题，欢迎评论区交流。