# ubbc-agent

**Repository Path**: andershsueh/ubbc-agent

## Basic Information

- **Project Name**: ubbc-agent
- **Description**: 用于检查ubbc的Agent
- **Primary Language**: NodeJS
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ubbc-agent

软通动力, 汽车图片合规检测工具 -2026。使用 LangGraph 多 Agent 工作流 + 火山方舟视觉模型，检测汽车外观/内饰图片中的违规信息。

[![License: Mulan PSL v2](https://img.shields.io/badge/License-Mulan%20PSL%20v2-blue.svg)](https://license.coscl.org.cn/MulanPSL2)

## 功能

- **8 类违规检测**：社会车牌、敏感内容、政治敏感、广告内容、友商信息、水印内容、二维码、vin码
- **LangGraph 多 Agent 工作流**：预处理 → 并行检测（文字类+视觉类）→ 汇总 → 交叉校验/深度验证 → 规则引擎 → 报告
- **多模型分工**：flash（快筛/预处理）、pro（文字OCR/视觉深检/交叉校验）、text（文本推理）
- **分类别置信度阈值**：每类违规独立阈值，如车牌 0.6、水印 0.5、广告 0.7
- **快筛机制**：批量检测自动启用两级过滤（本地预过滤 + VLM 快筛），成本降低 75%
- **例外规则**：支持品牌豁免（如懂车帝自身水印/品牌不判违规），配置化可调整
- **Function Calling**：文字类检测使用 Ark FC structured output，替代脆弱的 JSON 解析
- **模型降级**：模型不可用时自动降级到可用模型
- **规则热更新**：`role-settings.json` 变更自动生效，无需重启
- **单图 / 批量检测**：支持单张 URL 检测和批量文件输入
- **检测结果缓存**：SQLite 缓存，相同 URL 短期内不重复检测
- **日志轮转**：检测日志按小时轮转，7 天自动清理

## 快速开始

### 安装

```bash
git clone <repo-url>
cd ubbc-agent

# 创建虚拟环境
uv venv ubbc-venv --python 3.13
source ubbc-venv/bin/activate

# 安装
cd py_agent
uv pip install -e ".[dev]"
```

### 配置

1. 设置环境变量（在 `~/.zshrc` 或 `~/.bashrc` 中）：

```bash
export ARK_API_KEY="your-ark-api-key"
```

2. 首次运行自动创建 `~/.ubbc-agent/` 目录并复制默认配置模板。

3. 按需修改 `~/.ubbc-agent/role-settings.json` 中的违规规则和例外规则。

### 运行

```bash
# 单图检测
python -m ubbc_agent detect -p https://example.com/car.jpg

# 本地文件检测
python -m ubbc_agent detect -p ./car.jpg

# 批量检测（自动启用快筛）
python -m ubbc_agent detect -f url_list.txt

# 禁用快筛
python -m ubbc_agent detect -f url_list.txt --no-quick-scan

# 自定义快筛灵敏度
python -m ubbc_agent detect -f url_list.txt --scan-sensitivity high

# 指定并发数
python -m ubbc_agent detect -f url_list.txt -c 20

# 覆盖模型
python -m ubbc_agent detect -p https://example.com/car.jpg --model doubao-seed-2-0-pro-260215

# 详细日志
python -m ubbc_agent detect -p https://example.com/car.jpg --verbose

# 启动 API 服务
python -m ubbc_agent serve --port 8000
```

## 输出示例

**合规**：

```
检测结果: 合规
图片: https://example.com/car.jpg
耗时: 15000ms
模式: full
```

**违规**：

```
检测结果: 违规
图片: https://example.com/car2.jpg
耗时: 22000ms
模式: full

                                     违规项
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 类别     ┃ 严重度 ┃ 置信度 ┃ 描述                                            ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 社会车牌 │ medium │ 1.00   │ 图片前方可见蓝底白字车牌，号码为川F·2P9Z6      │
│ 友商信息 │ medium │ 1.00   │ 图片右下角检测到友商品牌"汽车之家"水印          │
│ 水印内容 │ low    │ 1.00   │ 水印内容为"汽车之家"文字标识                    │
└──────────┴────────┴────────┴─────────────────────────────────────────────────┘
```

## CLI 参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p, --probe <url\|path>` | 单图检测（URL 或本地路径） | - |
| `-f, --file <path>` | 批量检测，从文件读取 URL 列表 | - |
| `-c, --concurrency <n>` | 并发数 | 10 |
| `-o, --output <path>` | 输出文件路径 | stdout |
| `--rules <path>` | 规则文件路径 | ~/.ubbc-agent/role-settings.json |
| `--config <path>` | 配置文件路径 | ~/.ubbc-agent/settings.json |
| `--provider <name>` | 覆盖 API 提供商 | ark |
| `--model <model>` | 覆盖模型名称 | - |
| `--timeout <ms>` | 单请求超时 | 30000 |
| `--no-quick-scan` | 禁用快筛 | - |
| `--scan-sensitivity <level>` | 快筛灵敏度 (high/medium/low) | medium |
| `--verbose, -v` | 详细日志输出 | - |

## 检测流程

```
批量图片输入 (1~200张)
       │
       ▼
  batch_precheck ─── Level 0: 本地规则预过滤（零成本）
       │
       ▼
  quick_scan ──── Level 1: VLM 快筛（flash模型, 并发25, detail=low）
       │
  ┌────┴────┐
  safe     suspicious
  (PASS)   (深度检测)
              │
              ▼
         preprocess ─── 图片分类+质量评估+ROI（flash模型）
              │
         ┌────┴────┐                    并行
         │         │
  text_detection  visual_detection
  (pro,OCR+FC)    (pro,水印/VIN/二维码)
         │         │
         └────┬────┘                    汇总
              ▼
         aggregate ──── 汇总+冲突消解
              │
     ┌────────┼────────┐               条件路由
     │        │        │
 cross_check direct deep_verify
 (冲突校验) (合规)  (深度验证)
     │        │        │
     └────────┼────────┘
              ▼
       rule_engine ─── 分类别阈值+严重度+例外豁免
              │
              ▼
          report ──── 检测报告
```

## 例外规则

在 `role-settings.json` 的 `exceptions` 数组中配置，匹配到的违规项将被豁免：

```json
{
  "exceptions": [
    {
      "category": "水印内容",
      "description": "懂车帝自身水印豁免",
      "patterns": ["懂车帝", "dongchedi", "dongchedi.com", "dcarpai.online", "dcarimg.com"]
    }
  ]
}
```

## 项目结构

```
py_agent/                          # Python 3.13 + LangGraph 实现
├── pyproject.toml
├── settings.json                  # 默认配置模板
├── role-settings.json             # 默认规则+例外模板
├── src/ubbc_agent/
│   ├── cli.py                     # Typer CLI 入口
│   ├── agent/
│   │   ├── graph.py               # 单图检测 StateGraph
│   │   ├── batch_graph.py         # 批量检测 StateGraph
│   │   ├── state.py               # Pydantic State 定义
│   │   ├── nodes/                 # 检测节点
│   │   ├── routers/               # 条件路由
│   │   └── prompts/               # Prompt 模板
│   ├── api/
│   │   ├── ark_client.py          # Ark API 客户端
│   │   └── models.py              # 模型配置
│   ├── core/
│   │   ├── config.py              # 配置管理
│   │   ├── rule_loader.py         # 规则加载（热更新）
│   │   ├── cache.py               # SQLite 缓存
│   │   └── logger.py              # 日志管理
│   └── types/
│       ├── detection.py           # 检测结果类型
│       └── config.py              # 配置类型
└── tests/

node_cli/                          # 归档：旧版 Node.js 实现
```

## 开发

```bash
cd py_agent
source ../ubbc-venv/bin/activate
pip install -e ".[dev]"           # 开发模式安装
pytest                            # 运行测试
python -m ubbc_agent detect -p <url> --verbose  # 调试运行
```

## 许可证

[木兰宽松许可证第2版 (Mulan PSL v2)](https://license.coscl.org.cn/MulanPSL2)