Compliance Checker - 项目手续合规审查

核心能力

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

Python API

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

1. completeness - 文档批量嗅探

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

from compliance_checker.application.commands.completeness_cmd import run_completeness

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

参数：

返回值：

{
    "立项批复": {
        "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 - 时效性计算

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

from compliance_checker.application.commands.timeliness_cmd import run_timeliness

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

参数：

返回值：

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

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

3. visual - 视觉质检

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

from compliance_checker.application.commands.visual_cmd import run_visual

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

参数：

targets 命名规则：

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

返回值：

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

辅助函数

from compliance_checker.api import check_health

# 检查服务健康状态
health = await check_health()
print(health["status"])  # "healthy" 或 "unhealthy"

路径规则

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

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

典型工作流

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

1. 验证安装：首次使用前检查健康状态确认可用
2. 获取路径：必须从用户处获取具体的文件或目录路径
   • 如用户未提供路径，必须直接询问用户，不得自主探测
3. 分析用户意图：从用户描述中提取检查维度：
   • 需要检查哪些文件 -> 使用 run_completeness
   • 需要检查有效期 -> 使用 run_timeliness
   • 需要检查印章/签名 -> 使用 run_visual
4. 执行 API 调用：根据需要调用一个或多个函数
5. 汇总结果：直接处理返回的字典，向用户汇报

参数要求（安全规范）

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

Agent 行为约束：

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

示例：发票审查

from compliance_checker.application.commands.completeness_cmd import run_completeness
from compliance_checker.application.commands.timeliness_cmd import run_timeliness
from compliance_checker.application.commands.visual_cmd import run_visual

# 步骤1：检查发票文件是否存在
completeness_result = await run_completeness(
    path="D:/finance/invoices",
    documents=["增值税发票", "收据"]
)

# 步骤2：检查时效性
timeliness_result = await run_timeliness(
    file="D:/finance/invoices/增值税发票.pdf",
    reference_time="2026-03-15"
)

# 步骤3：检查印章
visual_result = await run_visual(
    file="D:/finance/invoices/增值税发票.pdf",
    targets=["发票专用章"]
)

示例：工程手续审查

# 步骤1：批量检查文件完整性
completeness = await run_completeness(
    path="D:/projects/building",
    documents=["立项批复", "环评批复", "施工许可证"]
)

# 步骤2：对每个找到的文件逐一检查时效性
for doc_name, doc_info in completeness.items():
    if doc_info:
        timeliness = await run_timeliness(file=doc_info["path"])
        print(f"{doc_name}: {timeliness['status']}")

# 步骤3：检查是否盖有公章
visual = await run_visual(
    file="D:/projects/building/立项批复.pdf",
    targets=["公章"]
)

错误处理

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

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}")

支持的文档格式

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

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

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

安装与配置（给用户）

安装

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

# 创建虚拟环境
python -m venv .venv

# Windows PowerShell 激活
.venvScriptsactivate

# 或 Windows CMD 激活
.venvScriptsactivate.bat

# 或 Linux/Mac 激活
source .venv/bin/activate

步骤 2：安装 compliance-checker

# 基础安装（不含 OCR 功能）
pip install compliance-checker

# 或安装阿里云 OCR 支持（云端 OCR，需网络）
pip install compliance-checker[cloud-ocr]

# 或安装本地 PaddleOCR 支持（本地 OCR，体积较大）
pip install compliance-checker[local-ocr]

# 或完整安装（包含所有可选依赖）
pip install compliance-checker[all]

验证安装

from compliance_checker.api import check_health
import compliance_checker

# 检查版本
print(compliance_checker.__version__)

# 检查健康状态
health = await check_health()
print(health["status"])

配置方式（SecretRef）

本 Skill 遵循 OpenClaw SecretRef 规范进行密钥管理，不支持直接读取环境变量。

必需配置

• llm_api_key: LLM API 密钥

可选配置

• llm_base_url: LLM API 端点（默认: https://api.openai.com/v1）
• llm_model: LLM 模型名称（默认: gpt-4o）
• llm_timeout: 请求超时（默认: 60秒）
• llm_max_retries: 最大重试次数（默认: 3）
• embed_api_key: 嵌入模型 API 密钥（默认使用 llm_api_key）
• embed_model: 嵌入模型名称（默认: text-embedding-v1）
• vision_api_key: 视觉模型 API 密钥（默认使用 llm_api_key）
• vision_model: 视觉模型名称（默认: qwen3-vl-flash）
• ocr_backend: OCR 后端（默认: none）
• alibaba_cloud_access_key_id: 阿里云 Access Key ID
• alibaba_cloud_access_key_secret: 阿里云 Access Key Secret

使用示例

from compliance_checker.infrastructure.config import CheckerConfig

# 使用 SecretRef 配置
config = CheckerConfig.from_secret_ref(
    secrets={
        "llm_api_key": {"source": "env", "provider": "default", "id": "LLM_API_KEY"},
        "llm_model": "qwen-max"
    }
)

数据隐私与合规声明 (Data Privacy Notice)

使用本工具时，您的文档数据可能会发送到外部服务：

视觉检测服务（visual API）

• 当调用 run_visual 时，文档图像及检测目标（targets）将通过 HTTPS 加密传输至配置的视觉模型服务端
• 默认使用阿里云 DashScope（LLM_BASE_URL），可通过配置切换到本地部署的 Vision 模型

OCR 服务（可选）

• OCR_BACKEND=none（默认）：本地处理，不发送数据
• OCR_BACKEND=paddle：本地 PaddleOCR，数据不离开本机
• OCR_BACKEND=aliyun：发送到阿里云 OCR 服务

安全建议

处理敏感 B2B 合规文档时，建议：

1. 配置本地部署的 Vision 模型端点
2. 将 OCR_BACKEND 设置为 paddle 使用本地 OCR
3. 通过私有 LLM 端点实现完全内网部署

本工具不会持久化存储您的文档内容。