原神桌面伙伴 · 项目详细介绍
当前版本:v3.8.4|平台:Windows(可跨平台移植) 运行环境:Python 3.14 + PySeide6 + pygame-ce|安装包:约 482 MB,每用户目录安装 本项目使用的原神素材不对外提供(仅供测试使用)。
更多详情请见 https://github.com/MrYuPengfei/Pilot-KG-Genshin/wiki
系统架构
1 分层总览
系统按「表现层 / 交互层 / 存储层 / 构建层」四段划分,依赖方向严格自上而下—— UI 不写 SQL,存储层不知道 Qt 存在。
┌──────────────────────────────────────────────────────────────┐
│ 表现层 pilot.Pilot manager_panel.ManagerPanel │
│ · QMainWindow + QSystemTrayIcon · 独立 QMainWindow │
│ · QTimer 驱动帧动画 · QTabWidget 六页 │
│ · QMenu + QAction 命令菜单 · 持有 pilot 引用 │
└───────────┬──────────────────────────────────┬───────────────┘
│ │
┌───────────▼──────────────────────────────────▼───────────────┐
│ 交互层 kg_view.KGCanvas / NodeItem kg_editor.*Dialog │
│ · QGraphicsView 自我中心网(懒展开) · EntityPicker 补全选择 │
│ · 纯展示,无任何写操作 · Node/EdgeEditDialog │
└───────────┬──────────────────────────────────────────────────┘
│
┌───────────▼──────────────────────────────────────────────────┐
│ 存储层(三库并列于程序目录 BASE_DIR,均为 SQLite) │
│ resource_store.ResourceStore → assets.db (帧/语音/BGM) │
│ config_store.ConfigStore → config.db (用户设置) │
│ kg_store.KGStore → kg.db (节点/关系) │
│ asset_importer / asset_exporter(跨库:素材 ↔ 配置联动) │
└───────────┬──────────────────────────────────────────────────┘
│ 仅构建期使用(不随包分发)
┌───────────▼──────────────────────────────────────────────────┐
│ 构建层 tools/build_assets_db.py · tools/build_databases.py │
│ data/csv/*.csv + data/config.json ──▶ 三个 .db │
│ res/help.html(外置帮助页)· ico/*.ico │
└──────────────────────────────────────────────────────────────┘
运行时只读三个 .db,彻底不读 CSV/JSON(已实测删掉整个 data/ 目录功能完整)。
CSV/JSON 降级为本地构建输入,只服务于「造出厂库」这一件事。
2 仓库目录结构
Pilot-KG-Genshin/
├── pilot.py 主程序(入口,含托盘菜单与动画主循环)
├── manager_panel.py 管理面板(QMainWindow 主窗口,任务栏独立图标)
├── resource_store.py 资源访问抽象层(优先 assets.db,回退文件系统)
├── config_store.py 配置存储层(config.db 持久化 + 导入导出)
├── asset_exporter.py 素材导出(assets.db → png/ 与 music/ 目录或 zip)
├── asset_importer.py 第三方素材包导入核心
├── kg_store.py 知识图谱存储层(kg.db 持久化 + CSV 导入导出 + 增删改)
├── kg_editor.py 知识图谱编辑对话框(实体属性表 / 关系两端选择)
├── kg_view.py 知识图谱可视化组件(自我中心网画布)
├── assets.db 资源数据库(由 tools/build_assets_db.py 构建)
├── kg.db 知识图谱数据库(由 tools/build_databases.py 构建)
├── config.db 出厂配置 + 用户本机设置(同一文件)
├── data/ ⚠️ 仅构建输入:既不入 git、也不随安装包分发
│ ├── config.json 出厂配置种子(构建 config.db 用,v3.8 起为 JSON)
│ ├── csv/ 原神知识图谱初始 CSV(27 个,构建 kg.db 用)
│ ├── csv-edu/ 教育 / AI 领域知识图谱初始 CSV(9 个)
│ ├── png/、music/ 原始素材目录(打包进 assets.db 后可不分发)
│ └── apng/、bgm/、spider-data/ 采集脚本的中间产物
├── res/
│ └── help.html 帮助文档(v3.8 外置,启动时动态读取)
├── ico/ 图标(icon256.ico / .bmp、app_icon.ico、logo.ico)
├── 桌面伙伴-Pilot.spec PyInstaller 打包配置
├── setup.iss Inno Setup 安装脚本(三处版本号同步点之一)
├── tools/ 构建、命令行与数据采集工具(17 个)
├── tests/ pytest 测试(18 个文件)
├── exhibition/ 各版本的项目详细介绍与配图
├── doc/ 部署说明、重构日志、知识图谱设计稿
...
data/整个目录不入 git(含 36 个知识图谱 CSV 与配置种子),新克隆需自行补齐—— 但它同时是打包的硬依赖,详见第九章。
3 模块职责
| 模块 | 行数 | 职责 |
|---|---|---|
pilot.py |
684 | 主类 Pilot:托盘、帧缓存、问候、音频、拖动、快捷键、单实例互斥量 |
manager_panel.py |
1570 | 六标签页管理面板、素材/配置/图谱的导入导出编排、帮助页加载 |
kg_store.py |
1444 | 图谱存储:SQLite 持久化 + 内存节点表/邻接表 + CSV 导入导出 + 节点关系编辑 |
kg_view.py |
496 | QGraphicsView 自我中心网画布(纯展示,不含写操作) |
kg_editor.py |
348 | 实体选择器与实体/关系编辑对话框 |
config_store.py |
399 | 配置存储:JSON 种子播种、kv + frame_scale 表、数值夹紧、JSON 导入导出 |
resource_store.py |
194 | 资源访问抽象层:优先 assets.db,回退文件系统;只暴露字节流与名称列表 |
asset_importer.py |
120 | 素材包(目录 / zip)→ assets.db upsert + 新人物登记 |
asset_exporter.py |
107 | assets.db → png/ + music/ 目录或 zip(与导入器严格对称) |
4 数据流
① 素材导入(跨两个库)
zip / 目录
│ asset_importer._extract_if_zip 解压到临时目录
▼
tools.build_assets_db.iter_assets 遍历并分类(frame / voice / bgm,语音按关键词归类)
│ INSERT OR REPLACE upsert
▼
assets.db ──────► config_store.register_role() 新人物补默认 [60ms, 1.0]
│
▼
Pilot.import_from_path → 内存 config 重新 load → _rebuild_role_menu()
→ 托盘菜单即时出现新人物
② 动画播放(性能关键路径)
QTimer.timeout ──► Pilot.act() 索引 +1 取模
│
▼
self._frames[i] ← 已在切换人物时全量预解码 + 预缩放 + 预 mask
│
▼
resize → setMask → setPixmap (顺序不能颠倒,见 4.9)
切换人物时一次性付清解码成本(219 帧约 0.5 s),动画期间磁盘 I/O 与重复解码降为 0。
③ 知识图谱编辑
kg_editor 对话框(只改内存字段)
│ 点确定后由调用方落库
▼
KGStore.add_node / update_edge_touching … with self._conn: ← 块退出即 commit
│
▼
kg.db ──► _reindex() 重建内存节点表与邻接表(2600 节点 / 8400 边,毫秒级)
│
▼
KGCanvas.show_ego() 重新绘制自我中心网
5 三库 schema
-- assets.db:单表存全部二进制资源(按 role + kind 建索引,列出某人物的帧只需走索引)
CREATE TABLE assets (
role TEXT NOT NULL, -- 角色名,或地区名(蒙德/璃月/稻妻)
kind TEXT NOT NULL, -- frame / voice / bgm
name TEXT NOT NULL, -- 原始文件名
category TEXT, -- 语音分类:greeting/chat/know
data BLOB NOT NULL,
PRIMARY KEY (role, kind, name)
);
CREATE INDEX idx_assets_role_kind ON assets(role, kind);
-- kg.db:节点 + 有向边(含权重)+ 中文名登记表 + 元信息
CREATE TABLE kg_nodes (
type TEXT NOT NULL,
name TEXT NOT NULL,
attrs TEXT NOT NULL DEFAULT '{}', -- attrs 为 JSON
PRIMARY KEY (type, name)
);
CREATE TABLE kg_edges (
id INTEGER PRIMARY KEY AUTOINCREMENT,
src_type TEXT NOT NULL,
src_name TEXT NOT NULL,
rel TEXT NOT NULL,
dst_type TEXT NOT NULL,
dst_name TEXT NOT NULL,
weight REAL, -- v3.5 起支持关系权重
UNIQUE (src_type, src_name, rel, dst_type, dst_name)
);
CREATE TABLE kg_rel_names (rel TEXT PRIMARY KEY, cn TEXT NOT NULL); -- 关系中文名单独立表
CREATE TABLE kg_type_names (type TEXT PRIMARY KEY, cn TEXT NOT NULL); -- 类型中文名持久化
CREATE TABLE kg_meta (key TEXT PRIMARY KEY, value TEXT); -- schema_version 等
-- config.db:标量项 + 人物帧率表 + 元信息
CREATE TABLE kv (key TEXT PRIMARY KEY, value TEXT); -- 标量项 JSON 编码
CREATE TABLE frame_scale (role TEXT PRIMARY KEY, interval INTEGER, scale REAL);
CREATE TABLE config_meta (key TEXT PRIMARY KEY, value TEXT); -- 播种来源 + schema_version
kg.db 与 config.db 都带 schema_version(分别为 3 与 1),为后续「服务端下发同格式数据」的
C/S 预留——结构版本不匹配时应拒绝导入而非静默出错。
kg_edges 的 weight 由 _migrate() 用 PRAGMA table_info 探测后 ALTER TABLE 补列:
CREATE TABLE IF NOT EXISTS 不会给已存在的表加列,这是老库升级时最容易漏掉的一步。
解析侧支持 8 / 0.85 / 8/10 / 8,5 / 1,000 多种写法,非法值退回默认而不丢边。
6 三个库的双重身份
kg.db 与 config.db 既是出厂产物,又是用户本机状态:程序里新增的图谱实体、
改过的名字、调好的帧率缩放都在里面。因此:
- 构建脚本默认不覆盖:
tools/build_databases.py不加--force时只检查不重建 (--force会自动备份为*.db.bak-<时间戳>); - 安装器用
onlyifdoesntexist安装:setup.iss的recursesubdirs复制_internal\*时把这两个库写进Excludes,再各自单独安装—— 否则升级一次就把用户编辑的图谱和设置清空; - 恢复出厂:删掉
config.db/kg.db后重装即可(面板因此不提供 「恢复出厂设置」按钮,避免误触)。
7 存储层的两条重要约定
① 内存索引加速 + 写后重建。 KGStore 以 SQLite 为准(唯一真身),
同时在内存维护 nodes 节点表、_name_index 名称索引、adj 邻接表、_edges 三元组集合。
查询走内存、写入落库后调 _reindex() 全量重建(2600 节点毫秒级,代价可接受,
换来的是不必维护增量一致性的复杂逻辑)。
② 导入必须单事务 + 事务内局部名称索引。 导入上千行 CSV 时,
self._name_index 在事务中不会刷新,因此必须在事务内维护一份局部索引,
否则本批新建的实体无法被后续关系解析。
一条容易忽略的顺序依赖:
adj是双向邻接表(入边出边都塞进去),所以它分不出方向。 需要方向时用neighbor_details_directed()(返回时带'out'/'in'标记), 或直接回self._edges查三元组的实际存储方向。
设计模式与工程实践
下面按「模式 → 在本项目中的具体落点 → 为什么这么用」列出。 其中部分模式是 GoF 经典模式,部分是为桌面应用形态做的显式取舍。
1 单例(Singleton)——模块级懒加载
kg_store.py 与 config_store.py 各有一份默认库单例:
_default = None
def get_default_store(base_dir=None, seed_dir=None, reset=False):
global _default
if _default is not None and not reset:
return _default
_default = KGStore(os.path.join(base_dir, 'kg.db'), seed_dir=seed_dir)
return _default
为什么需要:面板、图谱页、素材页都要访问图谱库。Qt 的信号槽是同步的,
若各处 KGStore(db_path) 各开一个连接,就会出现「一处写完、另一处索引还是旧的」。
单例保证全进程一份内存索引,跨窗口天然一致。
同时提供 reset_default_store() 供测试与「重载」丢弃实例——单例不等于不可回收。
2 存储抽象 / 后端策略(Strategy)+ 仓储(Repository)
ResourceStore 是唯一的资源入口,它在构造时决定后端:
if os.path.isfile(self.db_path):
self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
self.backend = 'sqlite'
else:
self.backend = 'filesystem'
上层(Pilot)只调 list_frames / read_frame / list_voices / read_bgm,
拿到的是字节流和名称列表,完全不关心底层是数据库还是目录。
为什么需要:开发期素材是零散的 png/ music/ 目录(近万个文件),
发布形态是单个 assets.db(461 MB)。两种形态必须都能跑,且上层代码一行不改。
这个「无数据库时回退文件系统」的能力让开发与发布可以各自选形态,
也让资源库缺失时的报错信息能明确指向补救方式。
三个存储类(ResourceStore / ConfigStore / KGStore)都遵守同一条纪律:
UI 不写 SQL,存储层不知道 Qt 存在。它们是三个独立的仓储,
各自拥有自己的 schema、播种策略与导入导出格式。
3 外观(Facade)与唯一入口收口
Pilot 是整个应用的外观门面,但更值得注意的是它把若干类操作收口到单一方法:
Pilot.set_visible(visible)是伙伴显隐的唯一入口。 托盘「显示」、桌面右键「隐藏」、 面板勾选项三者都走它;它末尾回调panel._sync_window_state()同步勾选状态。 v3.8 曾出现过的真实缺陷正是绕过它——从托盘隐藏伙伴后面板仍显示「已勾选」。Pilot.save_config()是配置落库的唯一入口,切换人物后立刻落库而不是等退出时保存, 这样程序被强杀下次启动仍是刚才那个人物。_sync_window_state()是面板状态同步的唯一入口, 由changeEvent与set_visible共同调用,保证「按钮文案 / 勾选 / 状态标签」三者不打架。
为什么重要:这是本项目踩过坑之后总结出的规则。多入口必然出现状态漂移, 而状态漂移是最难复现的一类 bug。收口到一处后,「哪些地方会改这个状态」永远可列举。
4 观察者(Observer)——Qt 信号槽
Qt 的信号槽机制本身就是 GoF 观察者的实现,项目中用它解耦了三处:
| 信号 | 槽 | 解耦了什么 |
|---|---|---|
QTimer.timeout |
Pilot.act |
定时器不关心谁在画帧 |
KGCanvas.nodeSelected / nodeExpanded |
面板填详情 / 重新展开 | 画布(纯展示)完全不知道面板的存在 |
tabs.currentChanged |
_ensure_kg_loaded |
懒加载挂在导航事件上,不需要额外的“加载”按钮 |
completer.activated |
补全回填 | 见 4.9,这是个踩过坑的观察者 |
5 模板方法(Template Method)——导入 / 导出的固定骨架
import_assets 与 export_assets 是同一骨架的镜像:
① 归一化输入(zip 解压 / 目录原样) → ② 遍历并分类 → ③ 写库或写文件 → ④ 报告
归一化那一步用 zipfile.is_zipfile(src) 判定并返回 (实际目录, 临时目录对象),
调用方用 try/finally 统一 tmp.cleanup()——分支只发生在第一步,
后面的流程对两种输入完全一致。
导出器则与导入器严格对称:png/<角色>/、music/<角色>/、
music/<地区>/background.mp3 三条布局约定两边一致,
保证「导出的包能被现有导入器直接并入」。这是刻意的:导出不是备份,是可逆操作。
6 空对象(Null Object)与静默兜底
多处「拿不到就退一步」的容错,构成事实上的空对象策略:
| 场景 | 兜底行为 |
|---|---|
| 配置种子文件缺失 / 损坏 | 静默退回内置 DEFAULTS,绝不抛异常(json.JSONDecodeError 全捕获) |
res/help.html 缺失 |
返回兜底提示页,面板照常打开 |
| 人物没录某时段问候语音 | 按降级顺序换关键词,全都没有就静默跳过 |
| 语音文件播放失败 | 捕获 RuntimeError 打印一行,不影响程序运行 |
| 磁盘图标缺失 | 退回当前伙伴的首帧当窗口图标 |
| 关系无中文名登记 | 回退静态 REL_NAMES,再回退英文原文,不报错也不吞掉 |
原则:程序永远能启动。所有外部输入(种子文件、素材包、用户导入的配置) 都视为不可信,解析失败时退回内置状态并留日志,而不是抛栈给用户看。
7 缓存(Cache)与写时失效
KGStore 的内存索引(4.2 已述)与 Pilot._frames 帧缓存是同一思路的两处应用:
- 帧缓存:切换人物时全量解码 + 预缩放 + 预生成
mask,动画期间零磁盘 I/O; 缩放变化(Ctrl + ↑/↓或面板改缩放)时整体重建。 - 索引缓存:查询全走内存,写入后
_reindex()全量重建—— 宁可重算 2600 个节点,也不去维护「增量更新邻接表」这类易错逻辑。
8 组合优于继承
v3.8 把管理面板从 QDialog 升级为独立 QMainWindow,
并显式断开 Qt 父子关系:构造时 super().__init__(None),
伙伴改由 self.pilot 属性引用。
这不是洁癖,是任务栏行为的硬约束:把 pilot 当 Qt 父窗口,
Windows 会把面板并进伙伴那个 Qt.Tool 窗口的任务栏分组,
任务栏上根本找不到面板。反过来伙伴本体加 Qt.Tool
(映射为 WS_EX_TOOLWINDOW)才让「桌面上只有一个托盘图标」成立。
面板关闭时 closeEvent 只做 event.ignore() + hide(),不销毁实例——
已填的表单与已加载的图谱要保住;真正的销毁只发生在 Pilot.quit() 里。
这里同时踩过一个坑:早期版本在 closeEvent 里调 pilot.on_manager_closed() 把 _panel 置空,
导致下次打开新建实例、旧实例泄漏——Qt 父子关系与 Python 引用是两套生命周期,不能混用。
9 适配器(Adapter):向 Qt 的缺陷妥协
几处 Qt / PySide6 不顺手的地方,用适配层包住,不让缺陷扩散到业务代码:
| Qt 的问题 | 适配做法 |
|---|---|
QCompleter.activated 有 QString 与 QModelIndex 两个重载,PySide6 不限定类型时只连得上前者 |
连接处用 signal[Type] 限定,或干脆不依赖信号参数,改从 completer.currentIndex() 反查 |
setMask 会把窗口 minimumSize 顶到遮罩尺寸,后续 resize 被 Qt 静默忽略 |
统一走 _apply_frame():resize → setMask → 显式 setMinimumSize(0, 0) |
setWindowFlags 会重置窗口几何,先 setGeometry 会被丢弃 |
窗口属性必须设在定位之前 |
QGraphicsItem 默认鼠标处理会 grabMouse(),对象被 scene.clear() 销毁后 Qt 报 ungrabMouse |
NodeItem 只响应「按下」,拖拽交给 QGraphicsView 的 ScrollHandDrag |
emit 是同步的,槽里销毁场景会让 super() 抛 Internal C++ object already deleted |
_retire_items() 主动置 _alive=False,重绘前置 False,事件开头检查即 return |
QColor 解析不了 CSS hsl(...)(isValid() 为 False,静默渲染成黑点) |
自动配色只存色相角,实际颜色由 _auto_color() 转成 #RRGGBB 后再入库 |
10 数据驱动的注册表(Registry)
实体类型、关系中文名、按钮尺寸这类元数据,全部收敛为模块级字典常量,
而不是散落在 if/elif 里:
NODE_TYPES = {'character': ('人物', '#e74c3c'), 'weapon': ('武器', '#8e44ad'), ...}
REL_NAMES = {'part_of': '属于', 'artifacts_is': '圣遗物', ...}
BTN_W, BTN_H = 132, 32
收益是新增一类实体只需加一行:图谱页的类型下拉、画布配色、详情页展示、
编辑器输入框会自动跟上。代价是要克制——REL_NAMES 里没有的关系
(用户自建的)显示时回退为原文,而不是报错或吞掉。
NODE_TYPES 还是个可增长注册表:register_type() 幂等且自动分配配色,
新增类型的中文名取该类型 label_cn / category 列的众数——
统计必须放在解析整张表的过程中,所以注册动作只能在 _parse_node_file 内部做。
手工路径的 add_node() 对未知类型仍然报错(打错字要当场拦住),自动注册只走导入路径。
同理,GREETING_SCHEDULE + GREETING_FALLBACKS 把「几点说什么话」
变成一张纯数据表,覆盖全天 24 小时(含跨零点区间),
并为每个时段定义降级顺序——新增时段不需要改代码:
GREETING_SCHEDULE = (
((23, 5), '晚安'), # 23:00~04:59(跨零点)
((5, 11), '早上好'), # 05:00~10:59
((11, 15), '中午好'), # 11:00~14:59
((15, 23), '晚上好'), # 15:00~22:59
)
11 命令(Command)与动态菜单
托盘菜单用 QAction + lambda 承载命令,菜单项由资源库动态生成:
def _rebuild_role_menu(self):
self.partners.clear()
available = set(self.store.list_roles())
ordered = [r for r in config['frame_scale'] if r in available] # 登记过的排前
ordered += sorted(available - set(ordered)) # 其余按字典序
for role in ordered:
act = QAction(role, self)
act.triggered.connect(lambda checked=False, r=role: self.reshow(r))
self.partners.addAction(act)
选中态用文案后缀("璃月~")而非勾选标记表达——托盘菜单是扁平结构,
后缀方案不需要额外维护 checked 状态,且点击时能从文案反推意图
(set_audio 收到带「~」就意味着“取消选中”)。