Hyps Hub 是 Hyps CLI 的原生 Linux 桌面客户端（Qt 6 / QML）， 目标是让你用图形界面完成 Hyps 的日常操作，同时保持 GUI 与 CLI 解耦、运行环境独立、数据隔离。
- 首次初始化向导：检查 Git / Bash / 网络，异步克隆独立的 Hyps 组件（带进度、失败可重试）。
- 完全隔离：Hyps 组件位于
$XDG_DATA_HOME/hyps-hub/runtime/Hyps；调用 CLI 时注入CONFIG_DIR / CACHE_DIR / DATA_DIR / TEMP_DIR，不写入~/Hyps，也不与~/.config/hypsc等目录混用。 - 环境检测：调用上游
init.sh --check并解析真实报表（必需项/可选能力/配置状态）。 - 游戏配置与启动：读取
CONFIG_DIR/games/*.conf，可视化编辑game.exe、runner.name、game.args等； 启动时调用上游scripts/<Game>.sh，实时显示 stdout/stderr、退出码，可按进程组取消任务。 - 终末地替身配置可视化：游戏页按游戏动态加载字段，
endfield额外提供「终末地替身」分区 （mode、launcher、替身目录/目标、硬链接与复制目标、keep、exit_after、show_info），mode用枚举选择，保存前校验模式冲突与「同一前缀dir/target二选一」。 - 配置管理：通用配置（MangoHud、GameMode、缓存、taskset、Overlay、时长记录等）与运行器配置可视化编辑；
保存前校验、自动
.bak.<时间戳>备份、原始文本编辑器（保留注释与顺序）。 - 任务与日志：任务历史（最多 200 条）、逐任务日志落盘、过滤/复制/清空视图、退出时清理子进程。
- 诊断：环境报表、Hyps 组件状态、手动检查更新（
git fetch+git merge --ff-only，脏工作区拒绝更新）、 白名单诊断命令、脱敏诊断包导出。 - 上游同步：跟随上游 Hyps 的配置契约变化（0.3.0 基线
a2ac842）。上游移除的功能（如 hosts 断网） 同步下线，只对残留键告警；弃用键（如gi.fps_unlock.prog）给出迁移提示而不改动用户配置。 - Material Design 3 界面：完整的 MD3 基线配色（浅/深两套语义色）、15 级字阶、形状/间距/状态层令牌；
46 个
Md*组件、导航轨 + 顶部应用栏 + 卡片式内容区，跟随系统深浅色并支持手动切换。 设计契约见 docs/design/MD3-SPEC.md。 - 界面可自检：
scripts/ui-audit.sh对 8 个页面 × 2 种窗口尺寸做几何审计（压扁/溢出/裁切/NaN） 并逐页渲染检查运行时警告；scripts/ui-geom.sh可导出每个控件的绝对坐标，用于排查像素级错位。
首次启动会进入独立的初始化向导：
- 检查 Git、Bash、数据目录与网络；缺失项会直接给出提示。
- 点击「开始初始化」后，异步克隆上游 Hyps 到
$XDG_DATA_HOME/hyps-hub/runtime/Hyps，显示进度与实时日志。 - 克隆完成后自动执行
init.sh --no-game，把配置写入隔离的CONFIG_DIR。 - 失败可安全重试；已存在的目标目录不会被覆盖，也不会触碰
~/Hyps。
- 四张状态卡展示应用版本、组件提交、CLI 可用性与依赖检测结果。
- 「环境检测」面板展示真实
init.sh --check报表，可滚动查看全部项目。 - 右侧展示最近任务与组件详情（提交、分支、工作区、CLI 入口）。
- 顶部可快速重新检测；底部「快捷操作」可直达游戏、配置与更新检查。
- 浅色主题下同一套语义色自动切换，版式与间距完全一致：
- 左侧列出
CONFIG_DIR/games/*.conf中的已配置游戏，并标注就绪/警告状态。 - 右侧可视化编辑
game.exe、runner.name、game.args等字段；保存前校验，并自动生成.bak.<时间戳>备份。 - 字段按游戏动态加载：
endfield会多出「终末地替身」分区（mode、launcher、替身目录/目标、hardlink_*/copy_*、keep、exit_after、show_info），mode为枚举选择，未启用时不生成替身。 - 底部显示启动命令与隔离环境；只有配置完整且已保存时「启动游戏」才可用。
- 启动通过上游
scripts/<Game>.sh执行，实时输出进入「任务」页。
- 点击「原始编辑器」会弹出独立大窗口，不再占用页面底部的小输入框。
- 编辑器支持横向与纵向滚动条（常显）、鼠标选择、
Ctrl+S保存。 - 「应用文本」只写入内存等待保存；「应用并保存」会校验、备份并落盘。
- 同一编辑器也用于通用配置与运行器配置。
- 来源是组件内的
config/games.examples，不会读取~/Hyps。 TEMPLATE表示隔离配置目录中还没有该游戏；点击「创建」复制示例配置，不会覆盖已有文件。- 创建后变为
CONFIGURED，再回到游戏页填写game.exe与运行器即可。
- 左侧任务列表显示状态、时间、耗时与退出码；右侧实时显示 stdout/stderr。
- 支持过滤、复制、清空视图、取消运行中的任务（按进程组终止）。
- 历史任务最多保留 200 条；每个任务的完整日志保存在
logs/tasks/。 - 重启后打开历史任务会自动从磁盘载入日志。
- 「通用配置」按功能分组展示 MangoHud、GameMode、缓存、taskset、Overlay、时长记录等开关。
- 每个字段可恢复默认（删除该键）；未知键可通过「原始编辑器」修改，保存前完整校验。
- 「运行器」只允许编辑隔离配置目录中的
runners/*.conf，来自组件的文件会标记只读。 - 保存前跑完整校验，有问题时逐条列出；路径类信息（配置/数据/状态/缓存/日志/组件根目录） 统一收在「设置 → 目录」，每行可复制或直接在文件管理器中打开。
- GUI 前置检查（Git/Bash/数据目录/网络/组件）全部来自真实检测。
- 环境报表、组件更新状态（
git fetch+git merge --ff-only，脏工作区拒绝）。 - 白名单诊断命令：环境检测、CLI 帮助、游戏列表、Proton 列表、游玩时长。
- 「原始报表」保留上游
init.sh --check的原文输出，便于对照 GUI 解析结果。 - 可导出脱敏诊断包（summary、环境报表、任务历史、日志尾部、SHA 说明）。
- 「外观」：主题跟随系统，也可固定浅色/深色；两套主题共用同一套 MD3 语义色与几何令牌。
- 「行为」：桌面通知（D-Bus，服务不可用时静默降级）、高级模式（显示原始编辑器与诊断命令）。
- 「目录」：配置/数据/状态/缓存/日志/组件根目录与 Hyps 配置目录，每行可复制或打开。
- 「运行环境」「窗口」：只读展示 Qt、系统、内核、会话与窗口状态；隐私说明与退出行为。
- 「构建信息」：应用版本、构建提交、Qt、系统、内核、会话。
- 「上游组件」：组件提交、分支、工作区、组件目录与 CLI 入口。
- 「数据隔离」：GUI 配置、组件、缓存、日志、任务日志各自的真实路径。
- 「常用命令」：CLI 入口与几个常用子命令，可直接复制。
- 「许可与致谢」：作者/维护者、GPL-3.0-only、原创资产声明与上游致谢。
运行时：
- Arch：
qt6-base qt6-declarative qt6-svg bash git - 运行游戏还需要上游 Hyps 所需的依赖（
umu-launcher、Proton、MangoHud、GameMode、gamescope 等）。 Hyps Hub 不重复实现这些依赖，只在诊断中展示缺失项。
构建：
sudo pacman -S --needed base-devel cmake ninja qt6-base qt6-declarative qt6-svgcmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build --output-on-failure
./build/hyps-hub或使用脚本：
./scripts/build.sh # 构建 + 测试
./scripts/run.sh # 构建后启动
./scripts/dev-run.sh # 开发模式：QML 走磁盘，改完自动重启（--bg 后台 / --stop 停止）./scripts/install-local.sh # 安装到 ~/.local# 在仓库根目录生成源码包（PKGBUILD 使用本地源码包）
git archive --prefix=hyps-hub-0.4.1/ -o hyps-hub-0.4.1.tar.gz HEAD
mkdir -p /tmp/hyps-hub-pkg && cp packaging/PKGBUILD hyps-hub-0.4.1.tar.gz /tmp/hyps-hub-pkg/
cd /tmp/hyps-hub-pkg && makepkg -f详见 docs/install.md。
当前版本 0.4.1，对应上游 Hyps 提交 a2ac842（基线 1b94dc8）。
| 上游变化 | Hyps Hub 处理 |
|---|---|
hosts_disconnect 功能移除 |
通用配置不再提供该字段；旧配置残留键只告警，不删除、不迁移 |
终末地替身配置重构（endfield.surrogate.*） |
游戏页新增「终末地替身」分区，并按上游语义校验模式冲突与目标互斥 |
gi.fps_unlock.prog 弃用 |
键仍可见可编辑，校验给出弃用提示（上游改为取 game.exe basename） |
组件升级仍走快进合并（git fetch + git merge --ff-only），脏工作区拒绝更新。逐提交的变更、
影响面与 GUI 适配明细见 docs/upstream-sync-2026-10-27.md。
| 路径 | 内容 |
|---|---|
~/.local/share/hyps-hub/runtime/Hyps |
独立 Hyps Git Hyps 组件 |
~/.local/share/hyps-hub/logs / cache / hyps-data |
日志、缓存、prefix/overlay/时长记录 |
~/.config/hyps-hub/config.json |
Hyps Hub 自身配置 |
~/.config/hyps-hub/hyps |
注入给 Hyps CLI 的 CONFIG_DIR |
~/.local/state/hyps-hub |
任务历史、环境检测结果、更新历史 |
实际路径按 XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_STATE_HOME 解析。
卸载应用不会删除 Hyps 组件、配置与日志；需要彻底清理时手动删除上述目录。
- 所有 CLI 调用都经过
HypsAdapter，使用程序 + 参数数组，不经过 shell，不提供任意命令执行器。 - 更新仅在 Git 工作区干净时执行
fetch+merge --ff-only；从不执行reset --hard/clean。 - Git 子进程使用净化后的环境，禁用仓库/全局钩子，并把
origin固定到编译期上游。 - 克隆失败只清理本次创建的
runtime/.Hyps.clone-*临时目录。 - 诊断导出对常见
Authorization: Bearer、--token/--password、JSON/引号值和 URL 凭据脱敏；仍建议分享前自行检查。 - 同一
XDG_STATE_HOME只允许一个实例，避免并发覆盖配置、任务历史或组件更新。 - 关闭窗口时检查运行任务和未保存配置；原始编辑器关闭时也会确认放弃修改。
- 默认拒绝 root；上游 CLI 本身也会拒绝 root。调试可用
--allow-root显式覆盖。
改界面不用重新编译：
./scripts/dev-run.sh # 从磁盘加载 QML，改完自动重启（--bg 后台 / --stop 停止）
./scripts/ui-audit.sh # 全页几何审计 + 运行时警告门禁（合入前必须 PASS）
./scripts/release-notes.sh # 从 CHANGELOG.md 抽出某版本段落（Release 正文就用它）架构、适配层契约、测试与设计规范见：
- CHANGELOG.md — 每个版本的完整变更记录
- docs/research.md — 上游调研、能力映射、技术选型
- docs/architecture.md — 分层、目录、状态机、适配层
- docs/development.md — 构建、测试、调试
- docs/verification.md — 构建、测试、打包与验收记录
- docs/upstream-sync-2026-10-27.md — 0.3.0 上游同步（
1b94dc8→a2ac842） - docs/troubleshooting.md — 故障排查
- docs/design/ — MD3 设计系统契约（
MD3-SPEC.md）与历史视觉参考归档
- 上游没有游戏库扫描、自动下载/安装游戏或 Proton 的能力，Hyps Hub 也不会伪造这些功能。
- 游戏启动的真实性依赖用户已安装的游戏与 Proton/umu 环境；自动化测试使用假 Hyps 组件验证适配层，不启动真实游戏。
- 游戏/Proton 进程继承真实
HOME与用户会话环境；本项目隔离 CLI 的 CONFIG/CACHE/DATA/TEMP，不是文件系统沙箱。 - 诊断导出在主线程执行；单个日志最多读取尾部 512 KiB、最多 10 个任务日志，但仍可能造成短暂 UI 停顿。
- 可访问性已补键盘导航与角色，但尚未做完整 WCAG/屏幕阅读器认证。
- 任务日志保留最近 200 个；清空历史会同时删除对应任务日志。运行日志按 2 MiB 轮转，更新历史保留最近 200 条。
- 更新使用 Git 快进合并；如果本地 Hyps 组件存在未提交修改，GUI 会拒绝更新，需要用户手动处理。
- 上游已移除 hosts 断网功能，Hyps Hub 同步下线；旧配置里的
features.hosts_disconnect.*残留键只告警，需自行清理。 - 终末地替身模式由上游 C 工具实现，需要
mingw-w64-gcc编译；launcher模式还要求本机已安装官方启动器。 - 未提供 Flatpak/AppImage：沙箱对宿主机 GPU/游戏环境有实际限制，不做未验证的交付。
- 未实现 P1/P2 的配置导入导出、桌面通知的细粒度设置、多运行环境模板等，详见架构文档。
GPL-3.0-only。上游 Hyps 亦为 GPL-3.0-only，但本项目不包含其源码；运行时由用户机器上的独立组件提供。
特别鸣谢 MoYingJi —— 上游 Hyps 的作者， 本项目的 CLI、初始化、配置格式与游戏启动逻辑均来自该项目。
- 上游项目：MoYingJi/Hyps（GPL-3.0-only）。Hyps Hub 不包含其源码。
- 设计规范：Material Design 3（Google，配色角色、字阶、形状、状态层、动效）。
- 框架与工具：Qt 6 / Qt Quick Controls 2、CMake、Ninja、GitHub Actions、Arch Linux
makepkg。 - 原创内容：应用 logo、
MdIcon自绘线性图标集、界面与文档；字体仅使用系统本地回退。
界面遵循 MD3 规范自行实现，不包含 Material Symbols 字体文件或其他第三方图标资产。 本项目与 Google 无隶属或背书关系。
完整来源、许可与致谢见 docs/credits.md。