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) - INLINECODE1 : structured CLI entrypoint
- INLINECODE2 : preserved legacy behavior implementation
- INLINECODE3 : module boundaries for maintainability
- INLINECODE4 : minimal regression coverage for compatibility-critical paths
Overview
多源动漫角色数据加载器，生成经过验证的 SOUL.generated.md 人格文件。
v2.3 关键改进:
- 1. 幂等合并: 同一角色多次合并不会重复
- 跨源一致性评分: AniList + Jikan 交叉验证
- 强制选择: 分数接近时强制用户选择
- 标准化退出码: 脚本可识别错误类型
Key Improvements (v2.3)
1. 退出码系统
CODEBLOCK0
2. 跨源一致性评分
CODEBLOCK1
3. 幂等合并
CODEBLOCK2
4. 强制消歧增强
CODEBLOCK3
Usage Examples
Basic Usage (Unique Names)
CODEBLOCK4
Disambiguation Required
CODEBLOCK5
Manual Selection
CODEBLOCK6
Preview Mode
CODEBLOCK7
Workflow
CODEBLOCK8
Configuration
强制消歧开关
CODEBLOCK9
强制选择阈值
CODEBLOCK10
置信度阈值
CODEBLOCK11
Error Handling
| 场景 | 退出码 | 处理 |
|---|
| API 失败 | 10 | 重试3次后退出 |
| 同名无提示 |
20 | 强制失败，提示用
--anime |
| 分数接近 | 20 | 强制失败，提示用
--select |
| 验证失败 | 30 | 回滚，可
--force 覆盖 |
| 文件写入失败 | 40 | 清理临时文件后退出 |
Cache & Performance
- - SQLite 缓存 (
~/.cache/anime-character-loader/) - 24小时过期
- 自动限流 (0.5s 间隔)
- 失败重试 (指数退避)
🔒 Privacy Notice
Data Sent to External Services
When you query a character name, the following data may be sent to external APIs:
| Service | URL | Data Sent | Purpose |
|---|
| AniList | INLINECODE9 | Character name | Primary character lookup |
| Jikan |
jikan.moe | Character name | MyAnimeList backup source |
| Fandom Wiki |
*.fandom.com | Character name + Anime name | Quotes and descriptions |
| 萌娘百科 |
zh.moegirl.org.cn | Character name | Chinese character database |
| yurippe API |
yurippe.vercel.app | Character name | Anime quotes database |
Privacy Protection
- - No personal data is collected or transmitted
- Only character names and anime titles are sent to external services
- All external requests use HTTPS encryption
- Local caching minimizes repeated external calls
Opt-Out Options
CODEBLOCK12
⚖️ Legal & Copyright Notice
Quotes Database
The local quotes database (data/quotes_database.json) contains:
- - Fan-collected quotes from anime/manga for educational/research purposes
- Fair use doctrine: Limited excerpts for character study and AI personality modeling
- All characters and works belong to their respective copyright holders
Wiki Content
Descriptions and excerpts are sourced from:
- - Fandom Wiki (CC-BY-SA license)
- 萌娘百科 Moegirlpedia (CC BY-NC-SA 3.0)
Usage Restrictions
- - ✅ Personal use and research
- ✅ OpenClaw agent personality configuration
- ❌ Commercial redistribution of quotes database
- ❌ Creating competing content databases
Copyright Holders
Characters referenced in this tool belong to their respective creators and publishers including but not limited to:
- - Saekano: © Fumiaki Maruto, Kurehito Misaki, KADOKAWA
- Rascal Does Not Dream: © Hajime Kamoshida, Keiji Mizoguchi, KADOKAWA
- And other respective copyright holders
For DMCA or copyright concerns, please contact through GitHub Issues.
🛡️ File Safety Notice
⚠️ Warning About File Operations
- - REPLACE mode will overwrite existing
SOUL.md (automatic backup created at SOUL.md.backup.YYYYMMDD_HHMMSS) - MERGE mode adds content without removing existing characters (idempotent - no duplicates)
- All write operations use atomic writes (temp file + rename)
Recommendation: Back up important SOUL.md files before using REPLACE mode.
Anime Character Loader v2.3
结构化架构（技能 + CLI）
本仓库采用技能 + CLI 混合架构：
- - loadcharacter.py：向后兼容的 CLI 命令（封装器）
- src/animecharacterloader/cli.py：结构化 CLI 入口点
- src/animecharacterloader/legacy.py：保留的旧版行为实现
- src/animecharacter_loader/{sources,disambiguation,generator,validator,storage}：模块边界，便于维护
- tests/：针对兼容性关键路径的最小回归测试覆盖
概述
多源动漫角色数据加载器，生成经过验证的 SOUL.generated.md 人格文件。
v2.3 关键改进：
- 1. 幂等合并：同一角色多次合并不会重复
- 跨源一致性评分：AniList + Jikan 交叉验证
- 强制选择：分数接近时强制用户选择
- 标准化退出码：脚本可识别错误类型
关键改进（v2.3）
1. 退出码系统
bash
0 # 成功
10 # 网络错误
20 # 数据错误（无匹配、消歧失败）
30 # 验证失败
40 # 文件错误
2. 跨源一致性评分
置信度 = (AniList 0.5 + Jikan 0.3) + (一致性 * 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
使用示例
基本用法（唯一名称）
bash
唯一名字可以直接生成
python load_character.py Kasumigaoka Utaha
python load_character.py 霞之丘诗羽
需要消歧
bash
同名角色必须指定作品
python load_character.py Sakura --anime Fate
python load_character.py Rin --anime Fate
python load_character.py Miku --anime Quintessential
手动选择
bash
列出所有匹配手动选择
python load_character.py Sakura --select 2
预览模式
bash
只查看信息不生成
python load_character.py 加藤惠 --info
工作流程
- 1. 名称翻译（中文→英文/日文）
↓
- 2. 多源并行查询（AniList + Jikan）
↓
- 3. 跨源一致性评分
- 计算名字相似度
- 计算作品相似度
- 综合置信度排序
↓
- 4. 强制消歧检查
- 多匹配？ → 需要 --anime
- 分数接近？ → 需要 --select
- 低置信？ → 需要 --anime
↓
- 5. 生成 SOUL.generated.md
↓
- 6. 语义验证（9项检查）
↓
- 7. 提示加载选项（REPLACE/MERGE/KEEP）
↓
- 8. 幂等合并（如选择 MERGE）
配置
强制消歧开关
python
在 load_character.py 顶部
FORCE_DISAMBIGUATION = True # 设为 False 恢复宽松模式
强制选择阈值
python
FORCE
SELECTIONTHRESHOLD = 0.15 # 分数差距小于此值强制选择
置信度阈值
python
CONFIDENCE
THRESHOLDHIGH = 0.8 # 高置信度
CONFIDENCE
THRESHOLDMEDIUM = 0.6 # 中等置信度
CONFIDENCE
THRESHOLDLOW = 0.5 # 最低接受线
错误处理
| 场景 | 退出码 | 处理 |
|---|
| API 失败 | 10 | 重试3次后退出 |
| 同名无提示 |
20 | 强制失败，提示用 --anime |
| 分数接近 | 20 | 强制失败，提示用 --select |
| 验证失败 | 30 | 回滚，可 --force 覆盖 |
| 文件写入失败 | 40 | 清理临时文件后退出 |
缓存与性能
- - SQLite 缓存（~/.cache/anime-character-loader/）
- 24小时过期
- 自动限流（0.5s 间隔）
- 失败重试（指数退避）
🔒 隐私声明
发送到外部服务的数据
当您查询角色名称时，以下数据可能会发送到外部 API：
| 服务 | URL | 发送的数据 | 用途 |
|---|
| AniList | anilist.co | 角色名称 | 主要角色查询 |
| Jikan |
jikan.moe | 角色名称 | MyAnimeList 备份源 |
| Fandom Wiki | *.fandom.com | 角色名称 + 动漫名称 | 台词和描述 |
| 萌娘百科 | zh.moegirl.org.cn | 角色名称 | 中文角色数据库 |
| yurippe API | yurippe.vercel.app | 角色名称 | 动漫台词数据库 |
隐私保护
- - 不收集或传输任何个人数据
- 仅向外部服务发送角色名称和动漫标题
- 所有外部请求均使用 HTTPS 加密
- 本地缓存最大限度地减少重复外部调用
退出选项
bash
禁用外部台词获取（仅使用本地数据库）
export DISABLE
EXTERNALQUOTES=1
python load_character.py 角色名称
⚖️ 法律与版权声明
台词数据库
本地台词数据库（data/quotes_database.json）包含：
- - 粉丝收集的台词，来自动漫/漫画，用于教育/研究目的
- 合理使用原则：用于角色研究和 AI 人格建模的有限摘录
- 所有角色和作品均属于其各自的版权所有者
Wiki 内容
描述和摘录来源：
- - Fandom Wiki（CC-BY-SA 许可）
- 萌娘百科 Moegirlpedia（CC BY-NC-SA 3.0）
使用限制
- - ✅ 个人使用和研究
- ✅ OpenClaw 代理人格配置
- ❌ 商业性再分发台词数据库
- ❌ 创建竞争性内容数据库
版权所有者
本工具中引用的角色属于其各自的创作者和出版商，包括但不限于：
- - 路人女主的养成方法：© 丸户史明、深崎暮人、KADOKAWA
- 青春猪头少年不会梦到兔女郎学姐：© 鸭志田一、沟口凯吉、KADOKAWA
- 以及其他各自的版权所有者
有关 DMCA 或版权问题，请通过 GitHub Issues 联系。
🛡️ 文件安全声明
⚠️ 关于文件操作的警告
- - REPLACE 模式将覆盖现有的 SOUL.md（自动备份创建于 SOUL.md.backup.YYYYMMDD_HHMMSS）
- MERGE 模式在不删除现有角色的情况下添加内容（幂等 - 无重复）
- 所有写操作均使用原子写入（临时文件 + 重命名）
建议：在使用 REPLACE 模式之前，请备份重要的 SOUL.md 文件。
