一个用 Python + PyQt6 写的桌面工具，用来管理 恋活 (Koikatu / KK) 与 恋活日光浴 (Koikatu Sunshine / KKS) 的角色卡：浏览、编辑、解包打包、伪装隐写、 Mod 缺失检测、场景卡提取、分享整理。
界面走克制的功能型风格——默认骨白·昼亮色主题启动（暗色党可切朱红·墨 或其它暗色方案），共 10 套可换肤。朱红 accent + 衬线标题 + 菱形 Logo， 暖墨基底与冷紫蓝 Dashboard 系工具刻意拉开距离。所有耗时操作放后台线程，不卡界面。
| 模块 | 说明 |
|---|---|
| 角色卡编辑 | 读写角色卡：姓名 / 昵称 / 性格 / 血型 / 社团 / 生日，以及 提问 / 特点 / H相关 三类勾选项与数值项；报告 / 卡片详情 / 解析JSON / 捏脸摘要四视图；预览写回差异、更换预览图、导出 JSON、最近打开列表、KK↔KKS 标识切换（实验，仅高级模式）。只写回用户改动的字段，不改即存=整文件字节级一致；默认另存为新卡，覆盖前自动备份。 |
| 卡片浏览器 | 扫描目录，识别角色卡 / 服装卡 / 场景卡，缩略图墙预览；左侧目录树导航（每文件夹带卡片计数、点击筛选）+ 库统计面板（全库 / KK / KKS / 各类卡计数）；类型筛选、名称搜索、双击进编辑器、导出卡片信息 CSV。 |
| 解包 / 打包 | zip 解包；把文件夹压缩后追加到真实视频/图片之后伪装（既能播放又能解压）；支持 AES-256 密码加密 / 多密码解密、分卷、解包操作选项（删源/清队列）；多重封缄（多层嵌套加密，解封按序提供全部密码、自动识别层数）与恢复校验清单（SHA256 检测损坏、逐文件定位 + 可选尾部冗余）；可选载体素材池（从目录随机抽载体，每次外壳不同）。 |
| Mod 仓库 | 扫描本地 .zipmod 读 manifest.xml 建 GUID 索引（增量更新，加 mod 后重建秒级）；从角色卡 / 场景卡提取依赖比对找缺失、导出缺失清单、复制可补 mod；按作者整理 / 归档未引用 / 清空索引 / 清单互助（导出本机清单、导入比对出可补给对方的、按清单直接导出压缩包）。 |
| 场景卡工具 | 从 Studio 场景卡提取内嵌角色卡（以脸图作封面，重建为可独立读取的标准卡）；分析场景内角色与依赖（内嵌角色 mod + 场景级 studio 道具）。 |
| 分享整理导入 | 四标签：生成分享包（卡片+依赖 mod）/ 导入恢复（包回灌游戏目录）/ 整理（按类型或角色名归类）/ 离线对账（目录按文件名比对，或带身份戳的清单对账：导出本机 Mod 清单、导入对方清单按 GUID 精确比对、一键复制可补给对方的 mod）。 |
| 运行日志 / 软件设置 | 操作记录；配置游戏目录、Mod 目录、输出目录；外观主题切换（内置 10 套 + 用户主题目录热加载）、普通 / 高级模式（普通模式收起封缄/分卷等高级项，界面更清爽）、标题栏样式（系统原生 / 无边框自绘）、库身份（展示名，用于清单对账）。 |
界面与主题：默认系统原生窗口（设置里可切换为无边框自绘标题栏，重启生效）。顶部横向导航带图标，卡片有轻投影分层。主题是精简的 JSON（约 15 个角色令牌，派生色自动算出），默认
bone_light（骨白·昼）/jade_dark（朱红·墨）；把自定义主题放进设置里指定的用户主题目录即可被加载，详见ui/themes/README.md。常用快捷键：
Ctrl+O读卡 ·Ctrl+S另存 ·Ctrl+F聚焦搜索 ·Ctrl+1~8切换页面。
直接双击 start.bat。首次运行会自动检查 Python 与依赖并补齐，然后启动程序。
python launch.py # 带依赖自检的启动器
# 或
pip install -r requirements.txt
python main.py环境要求：Python 3.9+，依赖 PyQt6 / msgpack / Pillow / pyzipper（加密打包用）/ Send2Trash（删除卡片走回收站）。launch.py 会自动补齐缺失依赖。
GitHub Releases 提供 PyInstaller 打包的单文件 KKTools.exe，无需安装 Python 即可运行。每次推送 v* 标签时由 GitHub Actions 自动构建。
- 编辑一张卡：把角色卡 PNG 拖进窗口，或在「角色卡编辑」点「读卡」。改完用「另存为新卡」。
- 整理收藏：「卡片浏览器」选目录扫描，按类型筛选，导出 CSV 管理。
- 查缺 mod：「软件设置」填好游戏目录 →「Mod 仓库」建立索引 → 拖卡进检查队列。
- 从场景扒人：「场景卡工具」选场景卡 →「提取角色到目录」。
- 打包分享：「分享整理导入」加卡 + 选输出目录 → 生成分享包（含依赖 mod）。
恋活角色卡是 PNG 图片 + 尾部追加的二进制块（MessagePack 序列化），核心解析器
core/kk_card.py 实现了安全的读写：
- 未编辑时字节级原样写回——读进来再存出去与原文件完全一致；
- 编辑时只重打包被改动的块（如 Parameter），其余块（Custom / Coordinate / KKEx / Status / About）字节级保留，最大限度避免破坏卡片；
- 已在真实 KK / KKS 角色卡上验证往返一致性与编辑安全性。
项目结构：
core/ 与界面无关的核心逻辑（卡片解析、Mod 索引、隐写/封缄、场景、分享、
主题、身份、清单、配置）—— 纯逻辑，不依赖 PyQt，可独立测试
ui/ PyQt6 界面（主窗、自绘标题栏、各功能页、主题模板/引擎、图标、后台线程、日志）
ui/themes/ 内置主题 JSON + 编写说明
ui/icons/ 自绘 SVG 图标
tests/ 核心逻辑单元测试
launch.py 启动器（依赖自检）
main.py 程序入口（含 apply_theme：加载主题→生成 QSS→应用）
运行测试：
python tests/test_kk_card.py # 卡片内核（字节级写回，7 用例）
python tests/test_theme.py # 主题引擎
python tests/test_stego_layered.py # 多重封缄 + 恢复校验
python tests/test_manifest.py # 库身份 + 清单对账
python tests/test_share_exclude.py # 分享包按清单排除 mod
python tests/test_gap3.py # 载体素材池 + 清单导出 zip- 本工具仅用于个人管理与编辑自己持有的角色卡 / mod，请遵守相关游戏与 mod 作者的使用条款。
- 「KK↔KKS 标识切换」为实验性功能（仅高级模式可见）：两作卡片结构本就不同（KKS 多 About 块与 interest 字段，捏脸/服装/mod 体系也不一样），仅切换标识不能真正跨作转换，转换后另一作大概率读取异常——仅供实验，请务必另存为新卡。
- 编辑卡片默认另存为新卡并在覆盖时自动备份，但仍建议对重要卡片自行留存原件。
- 恋活角色卡格式通过社区公开讨论与对真实卡片的逐字节分析得出。