二次元角色数据采集与识别工具集 + AI Agents + Electron 桌面应用
这是一个功能强大的 Python 工具集，采用模块化架构设计，用于自动化采集和识别二次元角色信息。项目整合了多个外部 API，支持从萌娘百科爬取角色数据，通过图片识别动漫/Galgame 角色，并使用 AI 生成角色的代表性台词（一言）。
核心特性：
- 🚀 高性能 FastAPI 架构：完全迁移至 FastAPI，支持异步并发处理
- 🏗️ 模块化路由系统：God Object 拆分，单一职责原则，易于维护
- 🤖 AI Agents 系统：智能体架构，支持动漫、游戏、漫画、小说、歌手、VTuber 等多种内容类型
- 🔍 15+ 识别器：整合 AnimeTrace、SauceNAO、Trace.moe 等多个识别 API
- ⚡ 异步并发：识别性能提升 3-5 倍，支持 HTTP/2
- 🎨 VLM/LLM 多模型支持：支持 DeepSeek、SiliconFlow、OpenAI、Claude、Gemini 等多个 AI 模型
- 🔄 LLM 配额管理：智能 429 重试机制，全局配额管理，调用串行化
- 💻 Electron 桌面应用：跨平台桌面客户端（Windows、macOS、Linux）
- 🌐 Web 可视化：现代化的 Vue.js 界面，支持国际化、主题切换
- 📊 实时通信：WebSocket 实时进度推送和任务控制
- 🛡️ 完整错误处理：40+ 错误代码、日志系统、错误统计
- 🔐 安全防护：依赖注入、API Key 验证、敏感操作保护
- 🗃️ SQLite 数据库：异步数据库操作，自动初始化，三级缓存策略
最新版本: v2.1.0 (2026年2月8日)
- Python 3.11+
- Node.js 18+ (用于 Electron 桌面应用)
- FFmpeg (用于视频处理)
# 安装 Python 依赖
pip install -r requirements.txt
# 安装 Playwright 浏览器
playwright install复制 .env.example 为 .env 并填入必要的 API Key：
cp .env.example .env必需配置：
# AI 服务提供商
SILICONFLOW_API_KEY=your_siliconflow_api_key_here
SAUCENAO_API_KEY=your_saucenao_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here可选配置：
# 会员开关
SAUCENAO_PREMIUM=False
TRACE_MOE_PREMIUM=False
# LLM 提供商选择
LLM_PROVIDER=deepseek
VLM_PROVIDER=siliconflow# 开发模式（支持热重载）- 推荐使用模块化架构
python -m src.server.main
# 或者直接使用应用工厂
python -m src.server.app
# 生产模式
uvicorn src.server.app:app --host 0.0.0.0 --port 5000 --workers 4服务器将在 http://localhost:5000 启动。
- 🏠 首页: http://localhost:5000/index.html
- 🤖 自动化助手: http://localhost:5000/assistant.html
- 📊 管理界面: http://localhost:5000/admin.html
- 🖼️ 映射关系: http://localhost:5000/mappings.html
- 💬 一言展示: http://localhost:5000/quote_view.html
- 📚 文档中心: http://localhost:5000/docs.html
cd electron
# 安装依赖
npm install
# 开发模式
npm run dev
# 构建应用
npm run build架构特点：
- 基于 FastAPI 的高性能异步 API 服务器
- 模块化路由系统：8 个独立路由模块（system, works, characters, images, identification, quotes, agent, static）
- God Object 拆分：
main.py（2300+ 行）拆分为模块化路由架构，符合单一职责原则 - 服务层拆分：QuoteService、IdentificationService、WallpaperService、BangumiImportService
- 应用工厂模式：
app.py统一管理生命周期、中间件与路由注册 - 依赖注入：统一的依赖管理（API Key 验证、数据库访问）
- 生命周期管理：自动初始化数据库、网络管理器、浏览器管理器
核心功能：
- RESTful API 接口
- API 版本化系统（v1/v2）
- 中间件系统（认证、速率限制、版本控制）
- 异步架构（Uvicorn ASGI 服务器）
- WebSocket 实时通信：SSE 流式接口，实时进度推送
- 批量任务管理：BatchTaskManager 统一管理，状态流转（Pause/Resume/Cancel）
- 静态文件服务
15+ 识别器：
- AnimeTrace - 高精度角色识别
- SauceNAO - 综合性图片识别
- IQDB - 反向图片搜索
- Trace.moe - 动画场景识别
- ASCII2D - 反向图片搜索
- Yandex - 综合性图片识别
- TinEye - 专业反向图片搜索
- GoogleLens - Google Lens 集成
- BingVisualSearch - Bing 视觉搜索
- AnimePictures - 动漫图片识别
- Danbooru - 基于 MD5 哈希的识别
- Baidu - 百度识图
- Sogou - 搜狗识图
- Google - Google Images 识别
- Waifu2x - 占位实现
技术特点：
- 异步并发识别（httpx.AsyncClient）
- 速率限制系统（自动遵守 API 频次限制）
- 统一识别器架构（BaseIdentifier）
- 自动图片压缩
- HTTP/2 支持
- 性能提升 3-5 倍
支持的智能体：
- 动漫智能体 (
anime_agent.py) - 游戏智能体 (
game_agent.py) - 漫画智能体 (
manga_agent.py) - 小说智能体 (
novel_agent.py) - 歌手智能体 (
singer_agent.py) - VTuber 智能体 (
vtuber_agent.py)
技术特点：
- 依赖注入重构（Phase 4）：所有智能体采用构造函数注入
- 工厂模式：
create_default()工厂方法创建实例 - 异步迁移：使用
AsyncLLMClient(httpx) - 优雅降级：增强的错误处理和 API Key 验证
- 自动识别内容类型
- 智能信息提取
- 多源数据整合
支持的提供商：
- DeepSeek：deepseek-chat
- SiliconFlow：DeepSeek-V3.2, Qwen2.5-VL-72B
- OpenAI：GPT-4o
- Claude：Claude Sonnet 4
- Gemini：Gemini 1.5 Flash
技术特点：
- 统一的 LLM 接口
- 自动重试和错误处理
- 请求缓存优化
- 429 配额超限处理
- 全局配额管理
- LLM 调用串行化
- 运行时配置切换
功能特性：
- 使用 AI 生成角色代表性台词
- 基于角色完整资料生成
- 支持多种 LLM 提供商
- 自动写入数据库
- 一言管理（搜索、删除）
- 批量生成
功能特性：
- 从萌娘百科自动爬取角色信息
- HTML 转 Markdown 格式
- 智能信息提取
- 支持批量处理
- 并发爬取
- 自动保存
SQLite 数据库：
- 异步数据库操作（aiosqlite）
- 自动初始化
- WAL 模式（提升并发性能）
- 三级缓存策略（内存、数据库、文件系统）
- 完整的 CRUD 操作
- 外键约束和级联删除
数据模型：
- 会社（Companies）
- 作品（Works）
- 角色（Characters）
- 图片（Images）
- 映射关系（Image Character Mappings）
- 一言（Quotes）
# 运行所有测试
pytest
# 运行特定模块
pytest tests/test_character_identifier.py
# 生成覆盖率报告
pytest --cov=src --cov-report=html
# 只运行失败的测试
pytest --lf
# 显示详细的局部变量
pytest -l- 测试文件：70+ 个
- 测试用例：1280 个
- 测试通过率：100%
- 目标覆盖率：95%
- 当前覆盖率：45%
tests/test_character_identifier.py- 识别器核心测试tests/test_api_server_async.py- 异步 API 服务器测试tests/test_batch_task_manager.py- 批量任务管理器测试tests/test_bangumi_local.py- Bangumi 本地数据测试tests/test_auto_complete_workflow.py- 完整工作流测试
pic&intro_provider/
├── src/ # 源代码目录
│ ├── config/ # 配置管理
│ ├── core/ # 核心功能模块
│ │ ├── api/ # API 客户端集成
│ │ ├── agents/ # AI 智能体系统
│ │ ├── crawlers/ # 数据爬取
│ │ ├── database/ # 数据库管理
│ │ ├── generators/ # 内容生成
│ │ ├── integrators/ # 数据整合
│ │ ├── processors/ # 数据处理
│ │ ├── services/ # 核心业务服务
│ │ └── utils/ # 通用工具
│ ├── server/ # Web 服务器
│ │ ├── routers/ # 路由模块（8个）
│ │ ├── services/ # 服务端服务
│ │ └── migrations/ # 数据库迁移
│ ├── middleware/ # 中间件系统
│ └── utils/ # 通用工具
├── tests/ # 测试目录
├── web/ # Web 前端
├── electron/ # Electron 桌面应用
├── docs/ # 文档目录
├── data/ # 数据目录
└── logs/ # 日志目录
# 启动开发服务器
python -m src.server.main
# 格式化代码
ruff format .
# 检查代码规范
ruff check .
# 运行测试
pytest
# 生成测试覆盖率报告
pytest --cov=src --cov-report=html# 初始化数据库
python -m src.core.database.database_init
# 查看数据库统计
python -c "from src.core.database.async_database_manager import AsyncDatabaseManager; import asyncio; asyncio.run(AsyncDatabaseManager().print_stats())"# 识别单张图片
python -m src.core.api.character_identifier data/input/image.jpg
# 批量识别
python -m src.core.processors.quick_batch_identify
# 智能搜图
python -m src.core.utils.smart_image_search data/input/image.jpg-
模块化架构（Phase 3）：
- God Object 拆分：
main.py（2300+ 行）→ 模块化路由架构 - 服务层拆分：QuoteService、IdentificationService、WallpaperService、BangumiImportService
- 应用工厂模式：
app.py统一管理生命周期、中间件与路由注册 - 单一职责原则（SRP）：每个路由文件负责特定功能
- God Object 拆分：
-
AI Agents 系统加固（Phase 4）：
- AnimeAgent 重构：移除隐式环境变量依赖，改为严格依赖注入
- 工厂模式统一：
create_default()工厂方法创建所有智能体实例 - SingerWikiAgent/NovelAgent 加固：采用相同的设计模式
- 异步迁移：使用
AsyncLLMClient(httpx) 全链路异步
-
测试验证（Phase 5）：
- BatchTaskManager 单元测试：完整覆盖状态流转（Pause/Resume/Cancel）
- 测试套件修复：适配新模块化架构
- 全量回归验证：确保重构未引入破坏性变更
- 测试用例：1280 个，100% 通过率
-
LLM 配额管理：
- 429 重试机制：自动检测配额超限，解析
retryDelay并重试 - 全局配额管理：
_llm_quota_exhausted标志，60 秒快速失败 - 调用串行化：
_llm_semaphore信号量控制并发
- 429 重试机制：自动检测配额超限，解析
-
其他核心特性：
- 异步高性能：全面的异步架构，性能提升 3-10 倍
- 依赖注入：统一的依赖管理，配置外部化
- 错误处理：40+ 错误代码，完整的日志系统
- 15+ 识别器：整合多个识别 API，异步并发识别
- AI Agents：智能体架构，支持多种内容类型
- VLM/LLM 多模型：支持 5 个主流 AI 提供商
- Electron 桌面应用：跨平台桌面客户端
- Web 可视化：现代化 Vue.js 界面
- 实时通信：WebSocket 实时进度推送
欢迎贡献代码！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'feat: 添加某个特性') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
使用中文提交信息，格式：
feat: 新功能fix: 修复 Bugdocs: 文档变更refactor: 代码重构test: 测试相关chore: 构建/依赖杂项
示例：
git commit -m "feat: 添加角色一言缓存机制"
git commit -m "fix: 修复识别器 HTTP 429 重试逻辑"本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情
- FastAPI - 现代化 Web 框架
- Vue.js - 渐进式 JavaScript 框架
- Electron - 跨平台桌面应用框架
- Playwright - 浏览器自动化工具
- PicImageSearch - 图片搜索库
版本: v2.1.0
更新日期: 2026年2月8日
维护者: iFlow CLI