# docfmt-agent

**Repository Path**: damengxiangjiaZTY/docfmt-agent

## Basic Information

- **Project Name**: docfmt-agent
- **Description**: DocFmtAgent 文档格式规范化智能体 — LLM Agent + Skills 架构的 Word(.docx) 格式检测/修正/示例学习全栈开源项目（FastAPI + Vue3 + python-docx）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocFmtAgent — 文档格式规范化智能体

> Document Format Standardization Agent — 面向「软件交付文档 + 招投标文件」的 Word(.docx) 格式规范化 AI Agent。
> **示例学习** 提炼规则 + **LLM Agent 自主决策**（规划 → 调 skills → 反思）+ **MySQL 持久化追溯**，只改格式、不改内容。

![License](https://img.shields.io/badge/License-MIT-blue)
![Python](https://img.shields.io/badge/Python-3.10%2B-green)
![Vue](https://img.shields.io/badge/Vue-3%20%2B%20Vite-brightgreen)
![Agent](https://img.shields.io/badge/Agent-tool_use%20%2B%20thinking-orange)

## 它能做什么

给一份排版混乱的 Word 文档，Agent 会：

1. **检测** — 对照格式规则模板，逐项检出字体 / 字号 / 对齐 / 缩进 / 行距 / 页面设置等问题（实测单文档 **53 个问题全量检出**）；
2. **修正** — 按规则一键修复，生成修正后文档 + 修改记录（实测 **53 → 0，问题 100% 消除**，内容与图片表格原样保留）；
3. **学习** — 给 1~N 份金标准样本，AI 自动提炼整套格式规则（19 个段落角色 + 文档级配置），生成可复用、可对话微调的个人模板。

## ✨ 核心特性

| 能力 | 说明 |
|---|---|
| 🔍 **智能检测** | 逐项检测字体/字号/对齐/缩进/行距/页面设置等格式问题 |
| 🔧 **一键修正** | 自动修复 + 修改记录，53→0 问题全量消除，内容零改动 |
| 🧠 **示例学习 ⭐** | 金标准样本 → 自动提炼格式规则（三层优先级：文字描述 > 批注 > XML + 众数/冲突识别），核心差异化创新 |
| 💭 **SSE 流式思维链** | 学习过程实时推送 thinking / tool_use / tool_result，看得见 LLM 在思考，不是黑盒等待 |
| 💬 **对话微调模板** | 自然语言调整模板（如"正文字号改小四"），带范围守护（越界拒绝 + 提醒） |
| 🗄️ **MySQL 持久化** | 模板微调修订记录（字段级 diff 追溯）+ 学习历史，全容错（连不上自动降级） |
| 🧩 **Skills 架构** | 9 个独立 skill 是前端与 Agent 共用的唯一能力底座，加目录即自动发现 |
| 📋 **全量格式字典** | 19 段落角色 + 文档级配置（页面/页码/编号/图表引用方式/缩进三态） |

## 🏗️ 系统架构

![DocFmtAgent 系统架构](docs/images/architecture.png)

```
frontend(Vue3) ──HTTP/SSE──► Agent(LLM tool_use loop) ──► skill_runtime
                                                        │
                                            ★ skills/（唯一能力底座，9 个）
                            detect_format / fix_format / learn_from_samples
                            evaluate_format / manage_template / update_template
                            xml_processing / format_extraction / style_application
                                                        │
                            ┌──────────────────────────┴────────────────────┐
                       src/core(确定性工具层)                          src/storage(db.py)
                       + src/rules(8 预置模板)                          MySQL 修订记录+学习历史
                       python-docx + lxml                               (全容错,连不上降级)
```

> Skills 分层的职责划分、改动红线见 [AGENTS.md](AGENTS.md)。

## 🚀 快速开始

### 前置

- Python ≥ 3.10
- Node.js（前端构建）
- MySQL（可选，留空则修订/历史功能自动降级，不影响主功能）

### 1. 配置凭证

```bash
cp .env.example .env
# 编辑 .env：
#   ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL / ANTHROPIC_MODEL
#     （Anthropic 官方 或 GLM 等兼容 Anthropic 协议的模型均可）
#   MYSQL_HOST / PORT / USER / PASSWORD / DATABASE  （留空 HOST = 持久化降级）
```

### 2. 启动后端（API，端口 8000）

```bash
pip install -r requirements.txt
uvicorn src.agent_runtime.server:app --port 8000
```

### 3. 启动前端（Vue，端口 5173）

```bash
cd frontend && npm install && npm run dev
```

浏览器访问 **http://127.0.0.1:5173**

### 4.（可选）直接调 skill / Agent

```bash
# 不走 LLM，直接调 skill（调试用）
python -c "from src.skill_runtime import call; print(call('detect_format', {'doc_path': '你的文档.docx'})['total'])"

# 走 LLM 的 Agent
python -m src.agent_runtime.agent "检测一份已上传或指定绝对路径的 .docx 文档格式问题"
```

## 🧩 9 个 Skills

| skill | 作用 | 输入 → 输出 |
|---|---|---|
| `detect_format` | 检测格式问题兼容入口 | `{doc_path, template?}` → `{total, by_severity, issues[]}` |
| `fix_format` | 一键修复兼容入口 | `{doc_path, out_path, template?}` → `{changes_applied, issues_after}` |
| `xml_processing` | DOCX XML 原子工具 | `{action, doc_path?, unpacked_dir?, output_path?}` → 包结构/校验结果 |
| `format_extraction` | 核心格式提取工作流 | `{doc_path, template?}` → `{outline, structure, issues, summary}` |
| `style_application` | 核心样式应用工作流 | `{doc_path, out_path, template?}` → `{changes_applied, issues_after, postcheck, preservation}` |
| `evaluate_format` | 格式质量评估/修订验收 | `{doc_path, fixed_doc_path?, template?, mode?}` → `{score, pass, issue_count, structure, before?, after?}` |
| `learn_from_samples` ⭐ | 从样本提炼规则 | `{sample_paths[]}` → `{rules(19角色), conflicts, missing, decisions}` |
| `manage_template` | 查看/列表/修订历史 | `{action, name?}` → 模板规则 / 修订记录 |
| `update_template` | 微调个人模板（范围守护） | `{name, changes, message}` → 更新后规则 + 修订记录 |

每个 skill 是独立目录（`SKILL.md` + `scripts/run.py`），核心 DOCX skill 进一步包含 `reference/` 与拆分脚本，结构对齐 Claude Code 原生复杂 skill 包。前端和 Agent 都经 `skill_runtime.call()` 调用；**新增能力 = 在 `skills/` 加目录，自动发现**。

## 📋 预置模板

`src/rules/presets/` 内置 8 类格式规则（均 19 角色全量）：

| 模板 | 用途 |
|---|---|
| `general_doc` | 通用公文行文规范（兜底模板） |
| `delivery_material` | 通用交付材料（默认） |
| `requirement_spec` | 需求规格说明书 |
| `overview_design` | 概要设计 |
| `detail_design` | 详细设计 |
| `user_manual` | 用户操作手册 |
| `test_report` | 测试报告 |
| `bidding_doc` | 招投标/应标文件 |

可经示例学习生成个人模板（保存到 `data/templates/`），并在模板管理页对话微调。

## 🗄️ MySQL 持久化

| 表 | 用途 | 写入时机 |
|---|---|---|
| `template_revisions` | 模板微调的字段级修订记录（role.field: old→new） | update_template 每次微调 |
| `learn_history` | 示例学习完整结果（报告 + 结构化 rules） | learn 完成时 |

全容错：MySQL 未配置 / 连不上 → 自动降级关闭，不影响检测/修复/学习/微调主流程。

## 📁 项目结构

```
docfmt-agent/
├── skills/                      # ⭐ skills 层（唯一能力底座）
│   ├── detect_format/           #   检测兼容入口（委托 format_extraction）
│   ├── fix_format/              #   修复兼容入口（委托 style_application）
│   ├── xml_processing/          #   DOCX OOXML 原子工具包
│   ├── format_extraction/       #   核心格式提取工作流 skill
│   ├── style_application/       #   核心样式应用工作流 skill
│   ├── evaluate_format/         #   格式质量评估/修订验收
│   ├── learn_from_samples/      #   示例学习（核心创新，三层优先级提取）
│   ├── manage_template/         #   模板管理
│   └── update_template/         #   模板微调（范围守护）
├── src/
│   ├── skill_runtime.py         #   skill 加载器/分发器（discover/call/as_tools）
│   ├── agent_runtime/           #   LLM 运行时：agent(run+run_stream) / server(FastAPI, SSE)
│   ├── core/                    #   确定性工具层：docx_io/classifier/detector/fixer
│   ├── rules/                   #   RoleRule(frozen) + presets/(8 预置模板)
│   ├── storage/                 #   MySQL 持久化（全容错）
│   └── utils/                   #   font_map（中英文字体映射）
├── frontend/                    # Vue3 + Vite 前端
├── docs/
│   ├── 全量格式字典.md           # ⭐ 19 角色格式规范 SSOT
│   ├── decisions/               # 架构设计文档
│   └── deploy/                  # Claude Code 运行时部署说明
└── tests/
```

## 🔧 技术栈

- **文档底座**：python-docx、lxml（中文字体 eastAsia 精确读写）
- **智能体**：Anthropic SDK（tool_use + thinking，兼容 Claude / GLM 等双协议模型）
- **核心检测/修订调度**（可选）：Claude Code + claude-agent-sdk（仅 `/api/detect/stream`、`/api/fix/stream`）
- **后端**：FastAPI + Uvicorn（SSE 流式）
- **前端**：Vue 3 + Vite
- **持久化**：MySQL（PyMySQL）

## 🗺️ 路线图

- [x] 工具层：53→0 问题（100% 消除）验证
- [x] Skills 层：9 个 skill（含核心 DOCX 工作流 + 评估验收 + 模板微调）
- [x] Agent 运行时：真 LLM tool_use + thinking + SSE 流式思维链
- [x] MySQL 持久化：修订记录 + 学习历史（全容错）
- [x] 全量格式字典：19 角色 + 图表引用方式
- [ ] 金标准样本集补充
- [ ] 单元/集成测试补齐（目标 ≥80% 覆盖）

## 📚 文档导航

| 文档 | 内容 |
|---|---|
| [AGENTS.md](AGENTS.md) | AI 编码助手工作指南（架构细节、改动红线、已知陷阱） |
| [docs/全量格式字典.md](docs/全量格式字典.md) | ⭐ 格式规范 SSOT：19 角色 + 文档级配置 |
| [docs/decisions/Agent能力设计.md](docs/decisions/Agent能力设计.md) | LLM Agent 能力设计 |
| [docs/decisions/整体框架与架构.md](docs/decisions/整体框架与架构.md) | 全栈架构、用户旅程 |
| [docs/decisions/Agent-Skills架构.md](docs/decisions/Agent-Skills架构.md) | Agent + Skills 架构定位 |
| [docs/deploy/claude-code-runtime.md](docs/deploy/claude-code-runtime.md) | Claude Code 运行时部署说明 |

## 📄 License

[MIT](LICENSE)