kimi-fabao — 智能文档结构识别引擎

基于 LLM 的嵌套文档结构提取工具
从 PDF / Word（含修订痕迹）中自动识别章节 → 条 → 款 → 项层级结构，输出结构化 JSON 与审阅报告。

---

核心特性

🔍 嵌套层级结构识别

自动识别法律合同中的多级嵌套结构，支持任意编号表述：

├── 第 {N} 章 / CHAPTER {N}     ← Level 1
│   ├── 第 {N} 条 / Article {N} ← Level 2
│   │   ├── {N}.1 / (1)          ← Level 3
│   │   └── {N}.2 / (2)          ← Level 3
│   └── 第 {N+1} 条               ← Level 2
└── ...

✏️ 追踪修订文档解析

Word 文档中的 w:ins（插入）和 w:del（删除）标记被完整保留：

block.revision.status   # INSERTED | DELETED | UNCHANGED
block.revision.author    # 修订作者
block.revision.date      # 修订时间
block.deleted_text       # 被删除的原始文本（用于对比审查）

🧠 混合提取策略（规则 + LLM）

输入文本 → 规则预识别 → LLM 提取 → Agent 自检 → 结构树
                ↓（置信度 < 阈值时触发）
           ContextAwareAgent 上下文重判

🏷️ 法律风险标签

基于语义分析自动标注风险条款：

标签	含义
违约金条款	约定了违约金或赔偿计算方式
竞业限制	限制离职后就业范围
连带责任	承担连带赔偿责任
保密义务	约定了保密责任
单方解除权	一方可单方面终止合同
不可抗力	约定了不可抗力条款
知识产权归属	约定了 IP 归属权

📊 多格式输出

格式	用途
JSON	程序化处理、数据库存储、RAG 向量化
Markdown	律师快速浏览、邮件转发
HTML 审阅报告	结构树 + 风险热力图 + 置信度标注

🤖 多 LLM 后端支持

后端	场景	配置
Kimi Code（推荐）	公司内部开发	LLM_PROVIDER=kimi_coding，自动使用 Claude Sonnet
Claude (Anthropic)	生产部署	ANTHROPIC_API_KEY
OpenAI 兼容	私有部署	OPENAI_API_KEY + LLM_BASE_URL

---

快速开始

安装

pip install kimi-fabao

或从源码安装：

git clone https://github.com/yourname/kimi-fabao.git
cd kimi-fabao
pip install -e .

环境配置

cp .env.example .env
# 编辑 .env，填入 API Key

Kimi Code 会员配置（推荐内部使用）：

LLM_PROVIDER=kimi_coding
LLM_BASE_URL=https://api.kimi.com/coding/
KIMI_CODE_API_KEY=sk-kimi-your-key-here
DEFAULT_MODEL=claude-sonnet-4-20250514

命令行使用

# 解析 PDF
python -m kimi_fabao input.pdf

# 解析 Word（含修订痕迹）
python -m kimi_fabao contract_tracked_changes.docx

# 输出为 Markdown
python -m kimi_fabao contract.docx --output markdown

# 输出为 HTML 审阅报告
python -m kimi_fabao contract.docx --output html

# 指定输出文件
python -m kimi_fabao contract.pdf --output json --out result.json

Python API

from kimi_fabao import DocumentProcessor

processor = DocumentProcessor()

# 解析合同
doc = processor.parse("contract.pdf")

# 查看结构
for section in doc.sections:
    print(f"{'  ' * section.level}{section.title} (置信度: {section.confidence:.0%})")

# 输出为 Markdown
md = processor.to_markdown(doc)
print(md)

从文本提取结构（无需文件）

from kimi_fabao.extractors import LLMStructureExtractor

text = """
第一章 总则
第一条 本合同依据《中华人民共和国民法典》制定。
第二条 甲方权利与义务。
第三条 乙方权利与义务。
"""

extractor = LLMStructureExtractor.from_env()
result = extractor.extract(text)

for block in result.structured_blocks:
    print(f"[Level {block.level}] {block.heading_text} (conf: {block.confidence:.0%})")

获取原始结果（JSON）

import json

result = extractor.extract(text)

# 转换为结构化 JSON
output = {
    "document_id": result.doc_id,
    "total_blocks": len(result.structured_blocks),
    "structure": [block.model_dump() for block in result.structured_blocks],
    "metadata": result.metadata,
}

print(json.dumps(output, ensure_ascii=False, indent=2))

---

项目架构

kimi-fabao/
├── src/kimi_fabao/
│   ├── parsers/                  # 文档解析层
│   │   ├── pdf_parser.py         #   PyMuPDF 提取 PDF 文本块 + 视觉特征
│   │   ├── docx_parser.py       #   lxml OOXML 解析（含 w:ins/w:del 修订追踪）
│   │   └── unified_parser.py    #   统一入口，自动识别文件类型
│   │
│   ├── core/                     # 核心数据模型
│   │   ├── models.py             #   Block, Section, Document (Pydantic v2)
│   │   └── extractor_protocol.py #   提取器接口协议
│   │
│   ├── extractors/               # 结构提取层
│   │   ├── base_extractor.py     #   基础提取器（滑窗、合并）
│   │   ├── llm_extractor.py      #   LLM 滑窗提取 + 结构树构建
│   │   └── hybrid_extractor.py   #   规则 + LLM 混合策略
│   │
│   ├── agent/                    # Agent 修正层
│   │   └── structure_agent.py    #   层级回溯、嵌套自检、上下文重判
│   │
│   ├── prompts/                  # Prompt 工程
│   │   └── structure_prompts.py  #   结构识别 few-shot 模板
│   │
│   ├── utils/                    # 工具函数
│   │   ├── chunking.py           #   滑动窗口分块
│   │   └── text_utils.py         #   文本处理工具
│   │
│   └── main.py                   # CLI 入口
│
├── docs/                         # 文档
│   ├── getting-started.md         #   快速入门
│   ├── architecture.md           #   架构设计详解
│   └── prompt-tuning.md          #   Prompt 调优指南
│
├── tests/                        # 测试
│   ├── unit/                     #   单元测试（覆盖率 ≥ 80%）
│   └── integration/             #   集成测试
│
├── examples/                     # 使用示例
│   ├── extract_pdf.py
│   └── extract_docx.py
│
└── scripts/                      # 开发脚本
    ├── test_kimi_structure.py   #   Kimi Code API 调试脚本
    ├── test_nda_structure.py    #   NDA 合同结构测试
    └── test_pdf_structure.py    #   PDF 结构测试

核心数据流

文件 (.pdf / .docx)
    ↓
Parser（解析器）
    ↓ [Block list: text + visual + revision]
Extractor（提取器）
    ├─ 规则预识别（正则/视觉）
    └─ LLM 滑窗提取（Confidence 标注）
    ↓ [StructuredBlock list]
StructureAgent（Agent 自检）
    ├─ 层级回溯（parent_id 补全）
    ├─ 嵌套自检（置信度 < 阈值 → 重判）
    └─ 上下文重判（模糊区域 Agent 重新理解）
    ↓ [Section tree]
Output（输出）
    ├─ JSON（程序化处理）
    ├─ Markdown（律师阅读）
    └─ HTML 审阅报告（风险热力图）

---

配置参数

环境变量	默认值	说明
LLM_PROVIDER	kimi_coding	提供商：anthropic / openai / kimi_coding
LLM_BASE_URL	https://api.kimi.com/coding/	自定义端点
DEFAULT_MODEL	claude-sonnet-4-20250514	Kimi Code / Anthropic 模型
MAX_TOKENS_PER_CALL	8000	单次调用最大输出
SLIDING_WINDOW_SIZE	40	滑窗每次处理的文本块数
SLIDING_WINDOW_OVERLAP	8	相邻窗口重叠块数
CONFIDENCE_THRESHOLD	0.75	低于此值触发 Agent 重判
ENABLE_RISK_DETECTION	true	是否开启风险标签检测

---

Roadmap

• output/ — Markdown / HTML 审阅报告生成器（结构树 + 风险热力图）
• evaluator/ — 结构识别准确率评估框架（benchmark）
• reviewer/ — 基于己方模板的合同比对工具（缺失条款检测）
• analysis/ — 条款语义分类器（甲方义务 / 乙方义务 / 共同约定）
• batch/ — 批量处理多份合同，横向对比报告
• MCP Server — Kimi CLI 直接调用封装
• Web UI — 交互式审阅界面

---

开发指南

本地运行测试

# 安装依赖
pip install -e ".[dev]"

# 运行单元测试
pytest tests/unit/ -v

# 运行集成测试
pytest tests/integration/ -v

# 运行带覆盖率测试
pytest --cov=src/kimi_fabao --cov-report=html

# 代码检查
ruff check src/
mypy src/

调试 LLM 调用

# 直接测试 Kimi Code 结构识别
python scripts/test_nda_structure.py

# 测试 PDF 结构识别
python scripts/test_pdf_structure.py

Prompt 调优

参考 docs/prompt-tuning.md，针对不同类型合同调整 few-shot 示例以提升识别准确率。

---

致谢

• Anthropic — Claude 模型
• Kimi — Kimi Code 平台
• PyMuPDF — PDF 解析
• python-docx — Word 文档解析

---

License

MIT License — 详见 LICENSE 文件。