原神桌面伙伴 · 项目详细介绍

当前版本: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 既是出厂产物,又是用户本机状态:程序里新增的图谱实体、 改过的名字、调好的帧率缩放都在里面。因此:

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 是整个应用的外观门面,但更值得注意的是它把若干类操作收口到单一方法:

为什么重要:这是本项目踩过坑之后总结出的规则。多入口必然出现状态漂移, 而状态漂移是最难复现的一类 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 帧缓存是同一思路的两处应用:

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 收到带「~」就意味着“取消选中”)。