Compliance Checker - 项目手续合规审查

核心能力

• - 资料完整性核对（精确+语义匹配文件名）
• 资料时效性核对（有效期判定）
• 视觉合规检测（Qwen-VL 识别印章/签名）

Python API

本工具提供 3 个原子 API 函数，直接返回 Python 字典，无需解析 JSON。

1. completeness - 文档批量嗅探

扫描目录中的文件，与给定文档名称列表做精确+语义匹配。

python
from compliancechecker.application.commands.completenesscmd import run_completeness

result = await run_completeness(
path=D:/docs,
documents=[立项批复, 环评报告, 施工许可证]
)

参数：

参数	类型	必需	说明
path	str	是	项目文件夹路径
documents

List[str] | 是 | 文档名称列表 |

返回值：

python
{
立项批复: {
path: D:/docs/立项批复.pdf,
similarity: 1.0,
match_type: exact
},
环评报告: {
path: D:/docs/环境评价报告.pdf,
similarity: 0.85,
match_type: semantic
},
施工许可证: None
}

• - match_type 为 exact 表示精确匹配（子串包含），semantic 表示语义匹配
• 值为 None 表示目录中未找到匹配文件

2. timeliness - 时效性计算

解析单个文件，提取日期信息，判定文档时效性状态。

python
from compliancechecker.application.commands.timelinesscmd import run_timeliness

result = await run_timeliness(
file=D:/docs/立项批复.pdf,
reference_time=2026-03-15 # 可选，默认为当前时间
)

参数：

参数	类型	必需	说明
file	str	是	文件路径（.pdf / .docx / .doc / 图片）
reference_time

str | 否 | 校验基准时间（YYYY-MM-DD），默认为当前时间 |

返回值：

python
{
status: VALID,
sign_date: 2025-06-15,
expiry_date: 2026-06-15,
validity: 365天,
branch: HAS_EXPIRY,
reason: 文件在有效期内
}

• - status: VALID（有效）/ EXPIRED（过期）/ UNKNOWN（无法判定）

3. visual - 视觉质检

检测文档中的印章、签名等视觉元素。

python
from compliancechecker.application.commands.visualcmd import run_visual

result = await run_visual(
file=D:/docs/立项批复.pdf,
targets=[公章, 法人签字]
)

参数：

参数	类型	必需	说明
file	str	是	文件路径（.pdf / 图片）
targets

List[str] | 是 | 检测目标列表（如[公章, 法人签字]） |

targets 命名规则：

• - 含章的视为印章检测（如公章、发票专用章、骑缝章）
• 含签的视为签名检测（如法人签字、经办人签名）
• 用户的原始 target 字符串会透传到 Qwen-VL 的 Prompt 中

返回值：

python
{
公章: {
found: True,
confidence: 0.95,
location: 右下角,
reasoning: 检测到红色圆形公章
},
法人签字: {
found: False,
confidence: 0.0,
location: ,
reasoning: 已检查 2 页，未找到法人签字
}
}

辅助函数

python
from compliancechecker.api import checkhealth

检查服务健康状态

health = await check_health() print(health[status]) # healthy 或 unhealthy

路径规则

传递路径参数时，建议使用正斜杠 (/)：

• - 推荐：D:/projects/docs
• 可用但不推荐：D:\projects\docs

典型工作流

当用户要求审查文档时，按以下步骤执行：

1. 1. 验证安装：首次使用前检查健康状态确认可用
2. 获取路径：必须从用户处获取具体的文件或目录路径

- 如用户未提供路径，必须直接询问用户，不得自主探测

1. 3. 分析用户意图：从用户描述中提取检查维度：

- 需要检查哪些文件 -> 使用 run_completeness - 需要检查有效期 -> 使用 run_timeliness - 需要检查印章/签名 -> 使用 run_visual

1. 4. 执行 API 调用：根据需要调用一个或多个函数
2. 汇总结果：直接处理返回的字典，向用户汇报

参数要求（安全规范）

所有 API 函数的路径参数均为严格必需：

函数	必需参数	说明
runcompleteness	path, documents	必须提供目录路径和文档列表
runtimeliness

file | 必须提供文件路径 |
| run_visual | file, targets | 必须提供文件路径和检测目标 |

Agent 行为约束：

• - 禁止自主探测路径：Agent 不得扫描文件系统
• 必须询问用户：如果用户请求中未提供具体的文件或目录路径，Agent 必须直接询问用户获取绝对路径
• 禁止猜测路径：Agent 不得假设或推断文件位置

示例：发票审查

python
from compliancechecker.application.commands.completenesscmd import run_completeness
from compliancechecker.application.commands.timelinesscmd import run_timeliness
from compliancechecker.application.commands.visualcmd import run_visual

步骤1：检查发票文件是否存在

completenessresult = await runcompleteness( path=D:/finance/invoices, documents=[增值税发票, 收据] )

步骤2：检查时效性

timelinessresult = await runtimeliness( file=D:/finance/invoices/增值税发票.pdf, reference_time=2026-03-15 )

步骤3：检查印章

visualresult = await runvisual( file=D:/finance/invoices/增值税发票.pdf, targets=[发票专用章] )

示例：工程手续审查

python

步骤1：批量检查文件完整性

completeness = await run_completeness(
path=D:/projects/building,
documents=[立项批复, 环评批复, 施工许可证]
)

步骤2：对每个找到的文件逐一检查时效性

for docname, docinfo in completeness.items(): if doc_info: timeliness = await runtimeliness(file=docinfo[path]) print(f{doc_name}: {timeliness[status]})

步骤3：检查是否盖有公章

visual = await run_visual( file=D:/projects/building/立项批复.pdf, targets=[公章] )

错误处理

所有错误以异常形式抛出，使用 try-except 捕获：

python
from compliance_checker.core.exceptions import ComplianceCheckerError

try:
result = await run_completeness(path=D:/nonexistent, documents=[test])
except FileNotFoundError as e:
print(f路径错误: {e})
except ValueError as e:
print(f参数错误: {e})
except ComplianceCheckerError as e:
print(f检查错误: {e})

错误类型	含义	恢复策略
FileNotFoundError	文件/目录不存在	请用户确认路径
ValueError

参数格式错误 | 检查参数格式（日期格式等） | | ComplianceCheckerError | 内部异常 | 检查环境配置和 API 密钥 |

支持的文档格式

• - PDF（支持 OCR 识别扫描件）
• Word（.docx, .doc）
• 图片（.png, .jpg, .jpeg）

支持的日期格式（timeliness 命令）

• - 2024年3月15日
• 2024-03-15
• 2024/03/15
• 2024年3月（自动补全为3月31日）

---

安装与配置（给用户）

安装

步骤 1：创建并激活虚拟环境（venv）

bash

创建虚拟环境