Anime Character Loader

# Anime Character Loader v2.3

## Structured Architecture (Skill + CLI)

This repository is organized as a skill + CLI hybrid:

- `load_character.py`: legacy-compatible CLI command (wrapper)
- `src/anime_character_loader/cli.py`: structured CLI entrypoint
- `src/anime_character_loader/legacy.py`: preserved legacy behavior implementation
- `src/anime_character_loader/{sources,disambiguation,generator,validator,storage}`: module boundaries for maintainability
- `tests/`: minimal regression coverage for compatibility-critical paths

## Overview

多源动漫角色数据加载器，生成经过验证的 SOUL.generated.md 人格文件。

**v2.3 关键改进**:
1. **幂等合并**: 同一角色多次合并不会重复
2. **跨源一致性评分**: AniList + Jikan 交叉验证
3. **强制选择**: 分数接近时强制用户选择
4. **标准化退出码**: 脚本可识别错误类型

## Key Improvements (v2.3)

### 1. 退出码系统
```bash
0   # 成功
10  # 网络错误
20  # 数据错误（无匹配、消歧失败）
30  # 验证失败
40  # 文件错误
```

### 2. 跨源一致性评分
```
Confidence = (AniList * 0.5 + Jikan * 0.3) + (Consistency * 0.2)

如果 top1 和 top2 差距 < 0.15:
    → 强制要求 --select 手动选择
```

### 3. 幂等合并
```bash
# 第一次合并
python load_character.py "Megumi" --anime "Saekano"
# 选择 MERGE → 添加角色

# 第二次合并（相同角色）
python load_character.py "Megumi" --anime "Saekano"  
# 选择 MERGE → 检测到重复，跳过

# 第三次合并（内容更新）
# 如果生成内容有变化 → 更新而非追加
```

### 4. 强制消歧增强
```bash
# ❌ 会失败 - Sakura 有多个角色
python load_character.py "Sakura"

# ❌ 即使指定作品，如果多个源返回相似结果
python load_character.py "Sakura" --anime "Fate"
# 可能仍要求 --select 如果 AniList 和 Jikan 结果不一致

# ✅ 必须手动选择
python load_character.py "Sakura" --anime "Fate" --select 1
```

## Usage Examples

### Basic Usage (Unique Names)
```bash
# 唯一名字可以直接生成
python load_character.py "Kasumigaoka Utaha"
python load_character.py "霞之丘诗羽"
```

### Disambiguation Required
```bash
# 同名角色必须指定作品
python load_character.py "Sakura" --...

# Anime Character Loader

> **输入角色名，生成可用 SOUL.generated.md，避免同名误判。**

Built by [Anchormind AI](https://anchormind-ai.com) — screen-free AI learning companions that actually see your books.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**核心价值**: 解决 AniList/Jikan 同名角色混淆问题，通过强制消歧 + 语义验证，确保输出可直接用于 OpenClaw 角色扮演。

**适合谁用**:
- OpenClaw/AI Agent 用户想快速加载动漫角色
- 角色扮演社区需要标准化 SOUL.md
- 开发者想批量生成角色配置文件

**3分钟上手**: 安装 → 运行命令 → 获得角色文件。

---

## Features

- 🔍 **Multi-source query**: Parallel search across AniList GraphQL + Jikan (MyAnimeList) APIs
- 🎯 **Forced disambiguation**: Requires `--anime` hint for ambiguous names (prevents wrong character selection)
- ✅ **Semantic validation**: 9-check validation system (structure + content quality)
- 🔄 **Idempotent merge**: Chapter-level merge with deduplication (same character won't be added twice)
- 💾 **Smart caching**: 24-hour SQLite cache with automatic retry logic
- 🎭 **Wikiquote Fetcher**: 3-phase台词抓取 (API → Browser → Local)，带置信度评分与Speaker识别
- Actual output example:
<img src="https://github.com/user-attachments/assets/41d52fb6-e82e-4e95-86a5-3a167042d53c" width="600" alt="对话演示">


## Installation

### As OpenClaw Skill (Recommended)

```bash
# Install via ClawHub
clawhub install anime-character-loader

# Or install from local clone
clawhub install ./anime-character-loader
```

Then use in OpenClaw:
```
@your_bot load_character "Kasumigaoka Utaha"
```

### As Standalone CLI

```bash
# Clone the repository
git clone https://github.com/colinchen4/anime-character-loader.git
cd anime-character-loader

# Install dependencies
pip install requests

# Run directly
python3 load_character.py "Kasumigaoka Utaha"
```

## Project Structure (Skill...