\r \r

Compliance Checker - 项目手续合规审查\r

\r

核心能力\r

\r

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

Python API\r

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

1. completeness - 文档批量嗅探\r

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

from compliance_checker.application.commands.completeness_cmd import run_completeness\r
\r
result = await run_completeness(\r
    path="D:/docs",\r
    documents=["立项批复", "环评报告", "施工许可证"]\r
)\r
```\r
\r
**参数：**\r
\r
| 参数 | 类型 | 必需 | 说明 |\r
|------|------|------|------|\r
| path | str | 是 | 项目文件夹路径 |\r
| documents | List[str] | 是 | 文档名称列表 |\r
\r
**返回值：**\r
\r
```python\r
{\r
    "立项批复": {\r
        "path": "D:/docs/立项批复.pdf",\r
        "similarity": 1.0,\r
        "match_type": "exact"\r
    },\r
    "环评报告": {\r
        "path": "D:/docs/环境评价报告.pdf",\r
        "similarity": 0.85,\r
        "match_type": "semantic"\r
    },\r
    "施工许可证": None\r
}\r
```\r
\r
- `match_type` 为 `exact` 表示精确匹配（子串包含），`semantic` 表示语义匹配\r
- 值为 `None` 表示目录中未找到匹配文件\r
\r
### 2. timeliness - 时效性计算\r
\r
解析单个文件，提取日期信息，判定文档时效性状态。\r
\r
```python\r
from compliance_checker.application.commands.timeliness_cmd import run_timeliness\r
\r
result = await run_timeliness(\r
    file="D:/docs/立项批复.pdf",\r
    reference_time="2026-03-15"  # 可选，默认为当前时间\r
)\r
```\r
\r
**参数：**\r
\r
| 参数 | 类型 | 必需 | 说明 |\r
|------|------|------|------|\r
| file | str | 是 | 文件路径（.pdf / .docx / .doc / 图片） |\r
| reference_time | str | 否 | 校验基准时间（YYYY-MM-DD），默认为当前时间 |\r
\r
**返回值：**\r
\r
```python\r
{\r
    "status": "VALID",\r
    "sign_date": "2025-06-15",\r
    "expiry_date": "2026-06-15",\r
    "validity": "365天",\r
    "branch": "HAS_EXPIRY",\r
    "reason": "文件在有效期内"\r
}\r
```\r
\r
- `status`: `VALID`（有效）/ `EXPIRED`（过期）/ `UNKNOWN`（无法判定）\r
\r
### 3. visual - 视觉质检\r
\r
检测文档中的印章、签名等视觉元素。\r
\r
```python\r
from compliance_checker.application.commands.visual_cmd import run_visual\r
\r
result = await run_visual(\r
    file="D:/docs/立项批复.pdf",\r
    targets=["公章", "法人签字"]\r
)\r
```\r
\r
**参数：**\r
\r
| 参数 | 类型 | 必需 | 说明 |\r
|------|------|------|------|\r
| file | str | 是 | 文件路径（.pdf / 图片） |\r
| targets | List[str] | 是 | 检测目标列表（如["公章", "法人签字"]） |\r
\r
**targets 命名规则：**\r
\r
- 含"章"的视为印章检测（如"公章"、"发票专用章"、"骑缝章"）\r
- 含"签"的视为签名检测（如"法人签字"、"经办人签名"）\r
- 用户的原始 target 字符串会透传到 Qwen-VL 的 Prompt 中\r
\r
**返回值：**\r
\r
```python\r
{\r
    "公章": {\r
        "found": True,\r
        "confidence": 0.95,\r
        "location": "右下角",\r
        "reasoning": "检测到红色圆形公章"\r
    },\r
    "法人签字": {\r
        "found": False,\r
        "confidence": 0.0,\r
        "location": "",\r
        "reasoning": "已检查 2 页，未找到法人签字"\r
    }\r
}\r
```\r
\r
## 辅助函数\r
\r
```python\r
from compliance_checker.api import check_health\r
\r
# 检查服务健康状态\r
health = await check_health()\r
print(health["status"])  # "healthy" 或 "unhealthy"\r
```\r
\r
## 路径规则\r
\r
传递路径参数时，**建议使用正斜杠 (/)**：\r
\r
- 推荐：`D:/projects/docs`\r
- 可用但不推荐：`D:\projects\docs`\r
\r
## 典型工作流\r
\r
当用户要求审查文档时，按以下步骤执行：\r
\r
1. **验证安装**：首次使用前检查健康状态确认可用\r
2. **获取路径**：**必须从用户处获取具体的文件或目录路径**\r
   - 如用户未提供路径，必须直接询问用户，不得自主探测\r
3. **分析用户意图**：从用户描述中提取检查维度：\r
   - 需要检查哪些文件 -> 使用 `run_completeness`\r
   - 需要检查有效期 -> 使用 `run_timeliness`\r
   - 需要检查印章/签名 -> 使用 `run_visual`\r
4. **执行 API 调用**：根据需要调用一个或多个函数\r
5. **汇总结果**：直接处理返回的字典，向用户汇报\r
\r
### 参数要求（安全规范）\r
\r
**所有 API 函数的路径参数均为严格必需：**\r
\r
| 函数 | 必需参数 | 说明 |\r
|------|----------|------|\r
| run_completeness | path, documents | 必须提供目录路径和文档列表 |\r
| run_timeliness | file | 必须提供文件路径 |\r
| run_visual | file, targets | 必须提供文件路径和检测目标 |\r
\r
**Agent 行为约束：**\r
- **禁止自主探测路径**：Agent 不得扫描文件系统\r
- **必须询问用户**：如果用户请求中未提供具体的文件或目录路径，Agent 必须直接询问用户获取绝对路径\r
- **禁止猜测路径**：Agent 不得假设或推断文件位置\r
\r
### 示例：发票审查\r
\r
```python\r
from compliance_checker.application.commands.completeness_cmd import run_completeness\r
from compliance_checker.application.commands.timeliness_cmd import run_timeliness\r
from compliance_checker.application.commands.visual_cmd import run_visual\r
\r
# 步骤1：检查发票文件是否存在\r
completeness_result = await run_completeness(\r
    path="D:/finance/invoices",\r
    documents=["增值税发票", "收据"]\r
)\r
\r
# 步骤2：检查时效性\r
timeliness_result = await run_timeliness(\r
    file="D:/finance/invoices/增值税发票.pdf",\r
    reference_time="2026-03-15"\r
)\r
\r
# 步骤3：检查印章\r
visual_result = await run_visual(\r
    file="D:/finance/invoices/增值税发票.pdf",\r
    targets=["发票专用章"]\r
)\r
```\r
\r
### 示例：工程手续审查\r
\r
```python\r
# 步骤1：批量检查文件完整性\r
completeness = await run_completeness(\r
    path="D:/projects/building",\r
    documents=["立项批复", "环评批复", "施工许可证"]\r
)\r
\r
# 步骤2：对每个找到的文件逐一检查时效性\r
for doc_name, doc_info in completeness.items():\r
    if doc_info:\r
        timeliness = await run_timeliness(file=doc_info["path"])\r
        print(f"{doc_name}: {timeliness['status']}")\r
\r
# 步骤3：检查是否盖有公章\r
visual = await run_visual(\r
    file="D:/projects/building/立项批复.pdf",\r
    targets=["公章"]\r
)\r
```\r
\r
## 错误处理\r
\r
所有错误以异常形式抛出，使用 try-except 捕获：\r
\r
```python\r
from compliance_checker.core.exceptions import ComplianceCheckerError\r
\r
try:\r
    result = await run_completeness(path="D:/nonexistent", documents=["test"])\r
except FileNotFoundError as e:\r
    print(f"路径错误: {e}")\r
except ValueError as e:\r
    print(f"参数错误: {e}")\r
except ComplianceCheckerError as e:\r
    print(f"检查错误: {e}")\r
```\r
\r
| 错误类型 | 含义 | 恢复策略 |\r
|----------|------|----------|\r
| FileNotFoundError | 文件/目录不存在 | 请用户确认路径 |\r
| ValueError | 参数格式错误 | 检查参数格式（日期格式等） |\r
| ComplianceCheckerError | 内部异常 | 检查环境配置和 API 密钥 |\r
\r
## 支持的文档格式\r
\r
- PDF（支持 OCR 识别扫描件）\r
- Word（.docx, .doc）\r
- 图片（.png, .jpg, .jpeg）\r
\r
## 支持的日期格式（timeliness 命令）\r
\r
- `2024年3月15日`\r
- `2024-03-15`\r
- `2024/03/15`\r
- `2024年3月`（自动补全为3月31日）\r
\r
---\r
\r
# 安装与配置（给用户）\r
\r
## 安装\r
\r
**步骤 1：创建并激活虚拟环境（venv）**\r
\r
```bash\r
# 创建虚拟环境\r
python -m venv .venv\r
\r
# Windows PowerShell 激活\r
.venv\Scripts\activate\r
\r
# 或 Windows CMD 激活\r
.venv\Scripts\activate.bat\r
\r
# 或 Linux/Mac 激活\r
source .venv/bin/activate\r
```\r
\r
**步骤 2：安装 compliance-checker**\r
\r
```bash\r
# 基础安装（不含 OCR 功能）\r
pip install compliance-checker\r
\r
# 或安装阿里云 OCR 支持（云端 OCR，需网络）\r
pip install compliance-checker[cloud-ocr]\r
\r
# 或安装本地 PaddleOCR 支持（本地 OCR，体积较大）\r
pip install compliance-checker[local-ocr]\r
\r
# 或完整安装（包含所有可选依赖）\r
pip install compliance-checker[all]\r
```\r
\r
## 验证安装\r
\r
```python\r
from compliance_checker.api import check_health\r
import compliance_checker\r
\r
# 检查版本\r
print(compliance_checker.__version__)\r
\r
# 检查健康状态\r
health = await check_health()\r
print(health["status"])\r
```\r
\r
## 配置方式（SecretRef）\r
\r
本 Skill 遵循 OpenClaw SecretRef 规范进行密钥管理，**不支持直接读取环境变量**。\r
\r
### 必需配置\r
\r
- `llm_api_key`: LLM API 密钥\r
\r
### 可选配置\r
\r
- `llm_base_url`: LLM API 端点（默认: https://api.openai.com/v1）\r
- `llm_model`: LLM 模型名称（默认: gpt-4o）\r
- `llm_timeout`: 请求超时（默认: 60秒）\r
- `llm_max_retries`: 最大重试次数（默认: 3）\r
- `embed_api_key`: 嵌入模型 API 密钥（默认使用 llm_api_key）\r
- `embed_model`: 嵌入模型名称（默认: text-embedding-v1）\r
- `vision_api_key`: 视觉模型 API 密钥（默认使用 llm_api_key）\r
- `vision_model`: 视觉模型名称（默认: qwen3-vl-flash）\r
- `ocr_backend`: OCR 后端（默认: none）\r
- `alibaba_cloud_access_key_id`: 阿里云 Access Key ID\r
- `alibaba_cloud_access_key_secret`: 阿里云 Access Key Secret\r
\r
### 使用示例\r
\r
```python\r
from compliance_checker.infrastructure.config import CheckerConfig\r
\r
# 使用 SecretRef 配置\r
config = CheckerConfig.from_secret_ref(\r
    secrets={\r
        "llm_api_key": {"source": "env", "provider": "default", "id": "LLM_API_KEY"},\r
        "llm_model": "qwen-max"\r
    }\r
)\r
```\r
\r
---\r
\r
# 数据隐私与合规声明 (Data Privacy Notice)\r
\r
使用本工具时，您的文档数据可能会发送到外部服务：\r
\r
### 视觉检测服务（visual API）\r
- 当调用 `run_visual` 时，文档图像及检测目标（targets）将通过 HTTPS 加密传输至配置的视觉模型服务端\r
- 默认使用阿里云 DashScope（`LLM_BASE_URL`），可通过配置切换到本地部署的 Vision 模型\r
\r
### OCR 服务（可选）\r
- `OCR_BACKEND=none`（默认）：本地处理，不发送数据\r
- `OCR_BACKEND=paddle`：本地 PaddleOCR，数据不离开本机\r
- `OCR_BACKEND=aliyun`：发送到阿里云 OCR 服务\r
\r
### 安全建议\r
处理敏感 B2B 合规文档时，建议：\r
1. 配置本地部署的 Vision 模型端点\r
2. 将 `OCR_BACKEND` 设置为 `paddle` 使用本地 OCR\r
3. 通过私有 LLM 端点实现完全内网部署\r
\r
**本工具不会持久化存储您的文档内容。**\r