在企业法务工作中，合同审核是高频且高风险的环节。传统的人工审核不仅耗时耗力，还容易因疲劳或经验差异导致关键条款的遗漏。随着大语言模型（LLM）技术的成熟，构建一个能够自动、智能、按既定规则审查合同的AI智能体（Agent）已成为可能。本文将手把手教你如何构建一个“Word Legal Agent”，它能够读取Word合同文档，并依据你预先定义的“Playbook”（检查剧本）进行自动化审查，输出结构化的风险报告与修改建议。无论你是希望提升法务效率的开发者，还是对AI应用落地方案感兴趣的技术人员，都能从本文中获得一套完整、可复现的实战方案。
1. 项目背景与核心概念
1.1 为什么需要合同审查AI Agent？
合同审查的核心是风险识别与条款完善。对于企业，尤其是中小企业，法务资源有限，但合同数量庞大、类型多样。人工审核面临几个痛点：
- 效率瓶颈：一份几十页的合同，逐字逐句审查可能需要数小时。
- 标准不一：不同法务人员的经验、侧重点不同，可能导致审查标准不统一。
- 疲劳疏漏：重复性劳动容易让人疲劳，从而忽略某些隐蔽的风险点，如争议解决条款中的细微差别、责任上限的绝对化表述等。
- 知识沉淀难：资深法务的经验难以快速、系统地转化为新人的能力。
AI Agent为解决这些问题提供了新思路。它不知疲倦，可以7x24小时工作；它严格遵循预设规则（Playbook），确保审查标准一致；它能快速处理海量文本，并基于庞大的法律知识库进行风险提示。
1.2 核心概念解析：Agent与Playbook
在开始构建之前，我们需要明确两个核心概念：
- AI Agent（智能体）：在本文语境下，它不是一个单一的模型，而是一个具备自主感知、决策和执行能力的软件系统。我们的“Word Legal Agent”需要能完成以下任务：
- 感知：读取并理解Word文档中的文本、段落结构乃至表格内容。
- 决策：根据“Playbook”中的规则，判断合同条款是否存在风险、是否缺失、是否合规。
- 执行：生成审查报告，甚至提出具体的修改建议文本。
- Playbook（检查剧本）：这是Agent的“大脑”和“行动指南”。它定义了审查的逻辑、规则和标准。一个合同审查Playbook通常包含：
- 审查维度：如合同主体、标的物、价款支付、交付验收、违约责任、知识产权、保密、争议解决等。
- 具体规则：每条规则对应一个具体的检查点。例如：
- “检查合同是否包含明确的争议解决条款（仲裁或诉讼）。”
- “检查违约责任中是否设定了过高的违约金比例（如超过合同总价的30%）。”
- “检查付款条件是否与交付里程碑明确挂钩。”
- 风险等级：为每条规则定义风险等级（如高、中、低），以便在报告中优先处理。
- 建议模板：为常见问题提供标准的修改建议或条款范本。
我们的目标：构建一个Agent，它能加载一个Word合同文件和一个结构化的Playbook配置文件，然后自动执行审查，并输出一份易于理解的报告。
2. 环境准备与项目结构
2.1 技术栈选择
为了实现上述目标，我们选择以下技术栈，兼顾功能强大与开发便捷：
- 编程语言：Python。因其在自然语言处理（NLP）、文档处理和AI集成方面的丰富生态。
- 文档处理：
python-docx库。用于读取.docx格式的Word文档，提取文本和基础结构信息。 - AI大模型接口：OpenAI API (GPT-4/3.5-Turbo) 或 国内兼容API（如智谱、DeepSeek）。这是Agent的“认知核心”，负责理解文本和基于Playbook进行推理。本文示例将使用OpenAI API格式，你可以替换为任何兼容的提供商。
- 配置管理：
PyYAML。用YAML格式来定义结构化的Playbook，清晰易读。 - 报告生成：
Jinja2。使用模板引擎来生成格式美观的HTML或Markdown审查报告。
2.2 环境搭建
- 创建项目目录：
mkdir word_legal_agent && cd word_legal_agent - 创建虚拟环境（推荐）：
python -m venv venv # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate - 安装依赖包： 创建
requirements.txt文件，内容如下：
执行安装：openai>=1.0.0 python-docx>=1.1.0 PyYAML>=6.0 Jinja2>=3.1.2 python-dotenv>=1.0.0pip install -r requirements.txt - 配置API密钥： 创建
.env文件（务必加入.gitignore），用于安全存储密钥：OPENAI_API_KEY=your_openai_api_key_here # 如果使用其他模型，可添加如： # ZHIPU_API_KEY=your_zhipu_api_key # BASE_URL=https://api.openai.com/v1 # 如需指向代理服务
2.3 项目结构设计
一个清晰的项目结构有助于代码维护和功能扩展。
word_legal_agent/ ├── .env # 环境变量（API密钥） ├── requirements.txt # 项目依赖 ├── config/ │ └── playbook.yaml # 审查剧本配置文件 ├── core/ # 核心模块 │ ├── __init__.py │ ├── document_reader.py # 文档读取器 │ ├── playbook_loader.py # Playbook加载器 │ ├── legal_agent.py # 核心Agent逻辑 │ └── report_generator.py# 报告生成器 ├── templates/ # Jinja2报告模板 │ └── report_template.html ├── data/ # 示例合同与输出 │ ├── sample_contract.docx │ └── outputs/ ├── main.py # 主程序入口 └── README.md3. 核心模块拆解与实现
3.1 文档读取器 (document_reader.py)
Agent需要“看到”合同。本模块负责从Word文档中提取纯文本，并尽可能保留一些结构信息（如标题）。
# core/document_reader.py from docx import Document from typing import List, Tuple class DocumentReader: def __init__(self, file_path: str): self.file_path = file_path self.doc = Document(file_path) def extract_full_text(self) -> str: """提取文档全部文本，合并段落。""" full_text = [] for paragraph in self.doc.paragraphs: if paragraph.text.strip(): # 忽略空行 full_text.append(paragraph.text) return '\n'.join(full_text) def extract_text_with_structure(self) -> List[Tuple[str, str]]: """ 提取带简单结构的文本。 返回一个列表，每个元素是 (段落样式, 文本内容)。 可用于识别标题、正文等（简化版）。 """ structured_text = [] for paragraph in self.doc.paragraphs: text = paragraph.text.strip() if text: # 简单判断：如果段落样式名包含‘Heading’，则认为是标题 style_name = paragraph.style.name if paragraph.style else 'Normal' structured_text.append((style_name, text)) return structured_text def get_metadata(self) -> dict: """获取文档基础元信息。""" core_props = self.doc.core_properties return { 'title': core_props.title, 'author': core_props.author, 'created': core_props.created, 'modified': core_props.modified, } if __name__ == "__main__": # 简单测试 reader = DocumentReader("../data/sample_contract.docx") print("文档前500字符：") print(reader.extract_full_text()[:500])3.2 Playbook加载器 (playbook_loader.py)
Playbook是Agent的规则库，我们用YAML来定义，因为它对人类友好且易于程序解析。
# config/playbook.yaml version: "1.0" name: "通用技术服务合同审查剧本" description: "适用于技术开发、咨询、服务类合同的初步风险审查。" rules: - id: R001 category: "合同主体" description: "检查合同双方名称、统一社会信用代码等主体信息是否完整、准确。" risk_level: "高" check_prompt: | 请审查合同文本中是否明确列出了甲方和乙方的完整公司名称、统一社会信用代码（或身份证号）及联系地址。 如果发现任何一方信息缺失或不清晰，请标记为问题。 suggestion_template: "建议在合同首部【甲方】、【乙方】部分明确填写完整的法律主体名称及统一社会信用代码。" - id: R002 category: "价款与支付" description: "检查合同总价是否明确，支付节点是否与交付物或里程碑挂钩。" risk_level: "高" check_prompt: | 请审查合同中的价款条款。确认： 1. 合同总价款是否以大小写两种形式明确写明。 2. 付款条件是否清晰（如预付款、验收后付款、尾款）。 3. 付款是否与明确的交付成果、里程碑或服务阶段挂钩。 如果价款不明确或付款条件过于模糊（如仅写‘项目完成后付款’），请标记为问题。 suggestion_template: "建议将付款与明确的交付里程碑绑定，例如：‘本合同总价款为人民币XX元（大写：XX元整），分三期支付：1. 合同签订后3个工作日内，支付30%作为预付款；2. 原型验收通过后，支付40%；3. 全部系统上线并终验合格后，支付剩余30%。’" - id: R003 category: "知识产权" description: "检查背景知识产权与项目成果知识产权的归属约定是否清晰。" risk_level: "高" check_prompt: | 请审查合同中关于知识产权的条款。重点关注： 1. 双方在合作前已拥有的知识产权（背景知识产权）是否明确归属各方，且约定在履行本合同过程中可免费使用。 2. 因履行本合同所产生的新的知识产权（项目成果知识产权）归属是否明确。通常应约定归委托方（甲方）所有，或双方共有。 3. 是否存在不合理的‘所有成果归受托方（乙方）所有’的条款。 如果知识产权条款缺失或约定对委托方不利，请标记为问题。 suggestion_template: "建议明确约定：‘双方各自拥有的背景知识产权归各自所有。乙方为履行本合同所产生的项目成果知识产权（包括但不限于源代码、技术文档、设计图等）所有权归甲方所有。甲方授予乙方为履行本合同目的所必需的免费使用权。’" - id: R004 category: "保密条款" description: "检查保密范围、期限和违约责任是否合理。" risk_level: "中" check_prompt: | 请审查合同的保密条款。确认： 1. 保密信息范围定义是否清晰（通常包括技术资料、商业计划、客户信息等）。 2. 保密期限是否合理（通常为合同期内及合同终止后2-3年）。 3. 违约责任是否具有可操作性。 如果保密条款过于宽泛或期限永久，可能对双方造成不当限制。 suggestion_template: "建议将保密期限修改为‘本协议有效期内及终止后两年’，并明确违约赔偿的计算依据，而非笼统的‘承担一切损失’。"对应的Python加载器：
# core/playbook_loader.py import yaml from typing import List, Dict, Any from dataclasses import dataclass from pathlib import Path @dataclass class Rule: id: str category: str description: str risk_level: str # 高， 中， 低 check_prompt: str suggestion_template: str class PlaybookLoader: def __init__(self, playbook_path: str): self.playbook_path = Path(playbook_path) def load(self) -> Dict[str, Any]: """加载并解析YAML格式的Playbook。""" if not self.playbook_path.exists(): raise FileNotFoundError(f"Playbook文件未找到: {self.playbook_path}") with open(self.playbook_path, 'r', encoding='utf-8') as f: data = yaml.safe_load(f) # 将规则列表转换为Rule对象列表 rules = [] for rule_data in data.get('rules', []): rules.append(Rule(**rule_data)) playbook_info = { 'version': data.get('version'), 'name': data.get('name'), 'description': data.get('description'), 'rules': rules } return playbook_info if __name__ == "__main__": loader = PlaybookLoader("../config/playbook.yaml") playbook = loader.load() print(f"Playbook名称: {playbook['name']}") print(f"包含规则数: {len(playbook['rules'])}") for rule in playbook['rules'][:2]: # 打印前两条规则 print(f" - {rule.id}: {rule.description}")3.3 核心Agent逻辑 (legal_agent.py)
这是项目的大脑，它协调文档读取、规则加载，并调用大模型API进行分析。
# core/legal_agent.py import os import json from typing import List, Dict, Any from openai import OpenAI from dotenv import load_dotenv from .document_reader import DocumentReader from .playbook_loader import PlaybookLoader, Rule load_dotenv() # 加载.env文件中的环境变量 class LegalAgent: def __init__(self, model: str = "gpt-4-turbo-preview"): """ 初始化Legal Agent。 :param model: 使用的LLM模型名称。 """ self.client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), # 如果使用其他兼容API，可在此指定base_url # base_url=os.getenv("BASE_URL", "https://api.openai.com/v1") ) self.model = model self.document_reader = None self.playbook = None def load_document(self, doc_path: str): """加载待审查的合同文档。""" self.document_reader = DocumentReader(doc_path) print(f"文档加载成功: {doc_path}") def load_playbook(self, playbook_path: str): """加载审查剧本。""" loader = PlaybookLoader(playbook_path) self.playbook = loader.load() print(f"Playbook加载成功: {self.playbook['name']}") def _call_llm_for_rule(self, rule: Rule, contract_text: str) -> Dict[str, Any]: """ 针对单条规则，调用LLM进行审查。 """ system_prompt = """你是一名专业的法律合同审查助手。请严格根据用户提供的审查规则（Check Prompt）来分析给定的合同文本。你的回答必须是纯JSON格式，包含以下三个字段： 1. `violation_found`: (布尔值) 合同文本是否违反了此规则或存在此规则描述的问题。 2. `risk_level`: (字符串) 直接返回规则中定义的`risk_level`，如“高”、“中”、“低”。 3. `analysis`: (字符串) 对问题进行简要分析，说明在合同文本中哪里发现了问题，依据是什么。 4. `suggestion`: (字符串) 如果`violation_found`为true，则根据规则的`suggestion_template`和具体问题，生成具体的修改建议或条款文本；如果为false，则此字段为空字符串""。 注意：只输出JSON，不要有任何其他解释。""" user_prompt = f""" 【审查规则】 {rule.check_prompt} 【合同文本】 {contract_text[:12000]} # 限制文本长度，防止超出模型上下文 请根据上述规则审查合同文本。 """ try: response = self.client.chat.completions.create( model=self.model, messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], temperature=0.1, # 低温度，保证输出稳定 response_format={"type": "json_object"} # 强制JSON输出 ) result = json.loads(response.choices[0].message.content) # 补充规则信息 result['rule_id'] = rule.id result['rule_category'] = rule.category result['rule_description'] = rule.description return result except Exception as e: print(f"调用LLM处理规则 {rule.id} 时出错: {e}") # 返回一个安全的默认结果 return { "rule_id": rule.id, "rule_category": rule.category, "violation_found": False, "risk_level": rule.risk_level, "analysis": f"分析过程中发生错误: {e}", "suggestion": "" } def review_contract(self) -> List[Dict[str, Any]]: """ 执行合同审查，遍历Playbook中的所有规则。 返回包含所有规则审查结果的列表。 """ if not self.document_reader or not self.playbook: raise ValueError("请先加载文档和Playbook。") contract_text = self.document_reader.extract_full_text() print(f"开始审查合同，合同长度: {len(contract_text)} 字符") print(f"将应用 {len(self.playbook['rules'])} 条规则...") review_results = [] for rule in self.playbook['rules']: print(f" 正在处理规则: {rule.id} - {rule.category}") result = self._call_llm_for_rule(rule, contract_text) review_results.append(result) print("合同审查完成。") return review_results3.4 报告生成器 (report_generator.py)
审查结果需要以友好的形式呈现。我们使用Jinja2模板生成HTML报告。
# core/report_generator.py from jinja2 import Environment, FileSystemLoader from typing import List, Dict, Any from datetime import datetime import os class ReportGenerator: def __init__(self, template_dir: str = "templates"): self.env = Environment(loader=FileSystemLoader(template_dir)) self.template = self.env.get_template("report_template.html") def generate_html_report(self, review_results: List[Dict[str, Any]], playbook_info: Dict[str, Any], doc_metadata: Dict[str, Any], output_path: str) -> str: """ 生成HTML格式的审查报告。 """ # 按风险等级和问题状态分类 high_risk_issues = [r for r in review_results if r['violation_found'] and r['risk_level'] == '高'] medium_risk_issues = [r for r in review_results if r['violation_found'] and r['risk_level'] == '中'] low_risk_issues = [r for r in review_results if r['violation_found'] and r['risk_level'] == '低'] passed_rules = [r for r in review_results if not r['violation_found']] context = { 'report_date': datetime.now().strftime("%Y-%m-%d %H:%M:%S"), 'playbook_name': playbook_info.get('name'), 'playbook_desc': playbook_info.get('description'), 'doc_title': doc_metadata.get('title', '未知合同'), 'doc_author': doc_metadata.get('author', '未知'), 'high_risk_issues': high_risk_issues, 'medium_risk_issues': medium_risk_issues, 'low_risk_issues': low_risk_issues, 'passed_rules': passed_rules, 'total_rules': len(review_results), 'issue_count': len(high_risk_issues) + len(medium_risk_issues) + len(low_risk_issues), } html_content = self.template.render(**context) os.makedirs(os.path.dirname(output_path), exist_ok=True) with open(output_path, 'w', encoding='utf-8') as f: f.write(html_content) print(f"HTML报告已生成: {output_path}") return output_path def generate_summary_markdown(self, review_results: List[Dict[str, Any]]) -> str: """生成一个简明的Markdown摘要，便于快速查看。""" issues = [r for r in review_results if r['violation_found']] if not issues: return "## 审查结果摘要\n\n✅ **所有检查项均通过，未发现明显风险。**" summary = ["## 审查结果摘要\n"] summary.append(f"**共发现 {len(issues)} 个潜在问题：**\n") for level in ['高', '中', '低']: level_issues = [i for i in issues if i['risk_level'] == level] if level_issues: summary.append(f"\n### ⚠️ {level}风险问题 ({len(level_issues)}个)") for issue in level_issues: summary.append(f"- **{issue['rule_id']} - {issue['rule_category']}**: {issue['analysis'][:100]}...") return '\n'.join(summary)对应的HTML报告模板 (templates/report_template.html)：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>合同智能审查报告</title> <style> body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; line-height: 1.6; color: #333; max-width: 1200px; margin: 0 auto; padding: 20px; } .header { border-bottom: 3px solid #2c3e50; padding-bottom: 20px; margin-bottom: 30px; } .header h1 { color: #2c3e50; } .meta { background-color: #f8f9fa; padding: 15px; border-radius: 5px; margin-bottom: 20px; } .meta table { width: 100%; border-collapse: collapse; } .meta td { padding: 8px 5px; border-bottom: 1px solid #dee2e6; } .meta td:first-child { font-weight: bold; width: 150px; } .risk-high { border-left: 5px solid #dc3545; background-color: #f8d7da; } .risk-medium { border-left: 5px solid #ffc107; background-color: #fff3cd; } .risk-low { border-left: 5px solid #28a745; background-color: #d4edda; } .issue-card { padding: 15px; margin-bottom: 20px; border-radius: 5px; } .rule-id { font-weight: bold; color: #495057; } .category { display: inline-block; background: #6c757d; color: white; padding: 3px 8px; border-radius: 3px; font-size: 0.8em; margin-left: 10px; } .suggestion { background-color: #e7f1ff; padding: 10px; border-radius: 5px; margin-top: 10px; border-left: 3px solid #007bff; } .passed { color: #28a745; } .summary-box { background: #e9ecef; padding: 20px; border-radius: 8px; margin: 30px 0; } </style> </head> <body> <div class="header"> <h1>📄 合同智能审查报告</h1> <p>基于Playbook: <strong>{{ playbook_name }}</strong> 自动生成</p> </div> <div class="meta"> <table> <tr><td>报告生成时间：</td><td>{{ report_date }}</td></tr> <tr><td>审查剧本：</td><td>{{ playbook_name }} ({{ playbook_desc }})</td></tr> <tr><td>审查文档：</td><td>{{ doc_title }}</td></tr> <tr><td>文档作者：</td><td>{{ doc_author }}</td></tr> <tr><td>审查统计：</td><td>共检查 {{ total_rules }} 条规则，发现 {{ issue_count }} 个潜在问题。</td></tr> </table> </div> <div class="summary-box"> <h2>📊 风险概览</h2> <p><span style="color:#dc3545;font-weight:bold;">高风险问题：{{ high_risk_issues|length }} 个</span> | <span style="color:#ffc107;font-weight:bold;">中风险问题：{{ medium_risk_issues|length }} 个</span> | <span style="color:#28a745;font-weight:bold;">低风险问题：{{ low_risk_issues|length }} 个</span> </p> <p>以下为发现的问题详情，请优先处理高风险项。</p> </div> {% if high_risk_issues %} <h2>🔴 高风险问题 (需立即关注)</h2> {% for issue in high_risk_issues %} <div class="issue-card risk-high"> <div><span class="rule-id">{{ issue.rule_id }}</span> <span class="category">{{ issue.rule_category }}</span></div> <p><strong>规则描述：</strong>{{ issue.rule_description }}</p> <p><strong>问题分析：</strong>{{ issue.analysis }}</p> <div class="suggestion"> <strong>修改建议：</strong><br>{{ issue.suggestion }} </div> </div> {% endfor %} {% endif %} {% if medium_risk_issues %} <h2>🟡 中风险问题 (建议修改)</h2> {% for issue in medium_risk_issues %} <div class="issue-card risk-medium"> <div><span class="rule-id">{{ issue.rule_id }}</span> <span class="category">{{ issue.rule_category }}</span></div> <p><strong>规则描述：</strong>{{ issue.rule_description }}</p> <p><strong>问题分析：</strong>{{ issue.analysis }}</p> <div class="suggestion"> <strong>修改建议：</strong><br>{{ issue.suggestion }} </div> </div> {% endfor %} {% endif %} {% if low_risk_issues %} <h2>🟢 低风险问题 (可选优化)</h2> {% for issue in low_risk_issues %} <div class="issue-card risk-low"> <div><span class="rule-id">{{ issue.rule_id }}</span> <span class="category">{{ issue.rule_category }}</span></div> <p><strong>规则描述：</strong>{{ issue.rule_description }}</p> <p><strong>问题分析：</strong>{{ issue.analysis }}</p> <div class="suggestion"> <strong>修改建议：</strong><br>{{ issue.suggestion }} </div> </div> {% endfor %} {% endif %} <h2>✅ 已通过检查的规则</h2> <p>以下 {{ passed_rules|length }} 条规则未在合同中发现问题，符合要求：</p> <ul> {% for rule in passed_rules %} <li><span class="passed">{{ rule.rule_id }} - {{ rule.rule_category }}</span>: {{ rule.rule_description }}</li> {% endfor %} </ul> <hr> <footer> <p><em>本报告由 Word Legal Agent 自动生成，仅供参考。重大合同决策请务必咨询专业律师。</em></p> </footer> </body> </html>4. 完整实战：运行你的第一个合同审查
现在，我们将所有模块串联起来，创建一个主程序并执行一次完整的合同审查。
4.1 准备示例合同
在data/目录下创建一个简单的示例合同sample_contract.docx，内容可以模拟一份有瑕疵的技术开发合同，例如故意缺失明确的付款节点、知识产权归属模糊等。
4.2 编写主程序 (main.py)
# main.py import sys import os sys.path.append(os.path.dirname(os.path.abspath(__file__))) from core.legal_agent import LegalAgent from core.report_generator import ReportGenerator def main(): # 1. 初始化Agent print("初始化 Legal Agent...") agent = LegalAgent(model="gpt-3.5-turbo-0125") # 可根据需要切换模型 # 2. 加载资源 contract_path = "./data/sample_contract.docx" playbook_path = "./config/playbook.yaml" try: agent.load_document(contract_path) agent.load_playbook(playbook_path) except FileNotFoundError as e: print(f"文件加载失败: {e}") return # 3. 执行审查 print("\n开始执行合同审查...") review_results = agent.review_contract() # 4. 生成报告 print("\n生成审查报告...") generator = ReportGenerator() # 获取文档元数据（用于报告） doc_metadata = agent.document_reader.get_metadata() if agent.document_reader else {} # 生成HTML详细报告 html_report_path = "./data/outputs/legal_review_report.html" generator.generate_html_report( review_results=review_results, playbook_info=agent.playbook, doc_metadata=doc_metadata, output_path=html_report_path ) # 生成并打印Markdown摘要 md_summary = generator.generate_summary_markdown(review_results) print("\n" + "="*50) print(md_summary) print("="*50) print(f"\n详细HTML报告已保存至: {os.path.abspath(html_report_path)}") if __name__ == "__main__": main()4.3 运行与查看结果
- 确保你的
.env文件中已配置正确的OPENAI_API_KEY。 - 在项目根目录下运行：
python main.py - 观察控制台输出，你会看到Agent加载文档、Playbook，逐条规则调用LLM，最后生成摘要。
- 打开
data/outputs/legal_review_report.html文件，你会看到一个格式清晰、风险分级、带有具体建议的完整审查报告。
5. 常见问题与排查思路
在开发和运行过程中，你可能会遇到以下问题：
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
ModuleNotFoundError: No module named 'openai' | 依赖未安装或虚拟环境未激活。 | 1. 确认虚拟环境已激活 (venv\Scripts\activate或source venv/bin/activate)。2. 运行 pip install -r requirements.txt。 |
openai.AuthenticationError | API密钥错误或未设置。 | 1. 检查.env文件是否存在，且OPENAI_API_KEY值正确。2. 确认运行环境能访问OpenAI API（网络问题）。 3. 如使用其他平台API，检查 base_url和api_key是否正确配置。 |
FileNotFoundError: Playbook文件未找到 | 配置文件路径错误。 | 1. 确认playbook.yaml文件在config/目录下。2. 在主程序中检查 playbook_path是否为相对或绝对正确路径。 |
docx.opc.exceptions.PackageNotFoundError | Word文档路径错误或文件不是有效的.docx格式。 | 1. 确认合同文件路径正确。 2. 尝试用MS Word或WPS重新保存文件为 .docx格式。 |
| LLM返回非JSON格式或解析错误 | 模型未遵循response_format指令，或check_prompt过于复杂导致。 | 1. 在_call_llm_for_rule方法中增加更严格的系统提示，强调“只输出JSON”。2. 在解析前加入 json.loads的异常捕获，并记录原始响应进行调试。3. 考虑使用更高阶的模型（如GPT-4）以获得更稳定的JSON输出。 |
| 审查结果不准确或遗漏 | 1. Playbook规则描述不清。 2. 合同文本过长，被截断。 3. 模型理解有偏差。 | 1.优化Playbook：确保check_prompt指令清晰、无歧义，使用明确的判断标准。2.分块处理：对于超长合同，可以按章节拆分后分别审查，再汇总结果。 3.人工复核：AI审查是辅助工具，所有高风险问题必须由法务人员最终确认。 |
| 运行速度慢 | 规则过多，串行调用API。 | 1.异步调用：使用asyncio和aiohttp并发处理多个规则审查请求。2.规则优先级：先运行高风险规则，或允许用户选择部分规则运行。 3.缓存：对未修改的合同和规则，可以缓存审查结果。 |
6. 最佳实践与工程化建议
将原型转化为一个稳定、可用的系统，还需要考虑以下方面：
6.1 Playbook设计最佳实践
- 规则原子化：每条规则应只检查一个明确的点。例如，将“检查付款条款”拆分为“检查总价是否明确”、“检查付款是否与里程碑挂钩”等独立规则。
- 提示词工程：
check_prompt是质量关键。使用清晰、具体的指令，并给出正反例子。例如：“如果合同中出现‘甲方可随时终止合同且不承担任何责任’的条款，请标记为高风险问题。” - 维护与版本控制：将Playbook文件纳入Git版本控制。当法律规范或公司政策变化时，可以方便地更新规则并追溯历史。
- 分类与标签：除了
category，可以为规则添加更多标签，如applicable_to（适用于采购/销售/雇佣合同），便于动态筛选。
6.2 系统性能与稳定性
- 异步处理：如前所述，使用异步IO并发调用LLM API，可大幅缩短审查时间。
- 速率限制与重试：在调用外部API时，必须实现指数退避的重试机制，并遵守API的速率限制（RPM/TPM）。
- 上下文长度管理：LLM有上下文窗口限制。对于超长合同，需要实现智能分块策略（如按章节、按页），并设计一个“总结-再分析”的流程，确保不丢失全局信息。
- 结果缓存：对相同的合同内容和Playbook版本，可以将审查结果缓存到数据库（如SQLite/Redis）中，避免重复计算和API调用。
6.3 安全与合规
- 敏感信息处理：合同是高度敏感的商业文件。确保系统部署在安全的内网环境，传输过程使用HTTPS，存储进行加密。可以考虑在调用API前对敏感字段（如金额、公司全称、身份证号）进行脱敏处理。
- 审计日志：记录每一次审查操作的元数据：谁、在何时、审查了哪个合同、使用了哪个Playbook版本、产生了什么结果。这对于合规审计和问题追溯至关重要。
- 人机协同：明确系统的定位是“辅助工具”。在报告显著位置注明“本报告由AI生成，仅供参考，不构成法律意见，最终决策需由专业法务人员做出。” 所有高风险问题的修改，必须经过人工确认。
6.4 扩展性设计
- 多格式支持：除了Word，可以扩展支持PDF、图片（OCR）、网页文本等格式的合同输入。
- 多模型支持：抽象LLM调用层，使其可以轻松切换不同的模型提供商（OpenAI、智谱、DeepSeek、本地部署的模型等）。
- 规则引擎：对于非常明确、固定的规则（如“合同必须包含双方盖章页”），可以先用正则表达式或简单NLP规则进行匹配，命中则直接返回结果，无需调用大模型，以节省成本和提高速度。
- 工作流集成：设计RESTful API，以便将本Agent集成到现有的合同管理系统（CLM）、OA或钉钉/飞书等办公平台中，实现从合同上传到报告返回的自动化流程。
构建一个企业级的合同审查AI Agent是一个持续迭代的过程。从本文这个可运行的原型出发，你可以根据实际业务需求，在规则精度、系统性能、用户体验和安全性上不断深化，最终打造出一个真正赋能法务团队、降低企业合规风险的智能工具。
