企业官网建设流程全解析

cua-hyprland-plugin 固定版本发布包安装、验证与运维全指南

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

本文基于 Cua 仓库中 Hyprland 输入插件的固定版本（pinned）发布流程，完整讲解如何在 Arch Linux x86_64 上从源码归档构建并安装cua-hyprland-plugin，如何用独立生命周期门禁在一次性环境中验证软件包事务，以及如何在全新桌面会话中激活输入、升级、回滚与卸载。读完本文，你将掌握一套"固定依赖契约 + 校验构建 + 隔离验证 + 新鲜会话激活"的严格发布运维流程，可直接复现于 Omarchy 等基于 Hyprland 0.56.2 的桌面环境。

固定版本发布包的设计背景

cua-hyprland-plugin是 Cua Driver 在 Hyprland 合成器上的原生输入候选模块，其发布方式与常规"下载即用"的二进制分发不同：本仓库只提供源码发行版（source distribution）与构建套件（build kit），不提供预编译模块。所有构建产物由发布环境之外的使用者按固定契约自行产出，并通过多层校验保证其与审核过的配方一致。

该机制由 hyprland-plugin/packaging/release/README.md 定义：源码归档生成器从显式允许列表中的 Git blob 生成确定性归档，生成cua-hyprland-plugin-DRIVER_VERSION-COMMIT_SHA.tar.gz（固定源码）与cua-hyprland-plugin-DRIVER_VERSION-COMMIT_SHA-build-kit.tar.gz（PKGBUILD、SOURCE-PROVENANCE.json、操作员README.md、lifecycle.py、SHA256SUMS）两个唯一命名归档，文件名内含发布版本号与完整源码提交 SHA。

需要特别强调的是发布包的能力边界：

• 源码生成器不做原生认证（native certification），其清单中的native_certified: false明确描述了这一限制（见 verify.py 中固定字段）；
• 校验和只能证明产物与已审核配方一致，不能单独证明原生兼容性；
• 使用候选模块前，应查阅该发布版单独的 native evidence（原生证据），确认精确的源码修订与环境。

构建与安装：严格遵循固定依赖契约

构建契约（Build Contract）

受支持的构建契约是Linux x86_64 + Hyprland0.56.2-1+ 头文件0.56.2+ GCC16.1.1 20260728+ 共享libstdc++.so.6.0.36。编译器、合成器、模块三者必须解析到相同的运行时字节（同一 ELF ABI 注释、同一共享 C++ 运行时）。一个更新的软件包或编译器不满足该契约——这就是"固定"二字的含义。

备注：仓库中另有 schema 2 的 profile 机制（见 profiles/omarchy-stable-20260910.json），允许以独立审核过的 profile 锁定 GCC16.2.1与 Hyprland0.56.2-2等更新组合；使用 profile kit 时以该 profile 的字段为准。本文主体仍以 USAGE.md 的默认 schema 1 契约为准。

配方（recipe）不会安装工具链，也不修改运行时搜索路径，因此必须在目标环境中预先安排固定依赖。

下载与校验归档

从同一个组件发布版下载源码归档与配套的 build kit，两者文件名中的DRIVER_VERSION与COMMIT_SHA必须完全一致。在专用空目录中解压 build kit，并将源码归档放在其旁边，与PKGBUILD、SOURCE-PROVENANCE.json、README.md、lifecycle.py、SHA256SUMS同目录。先对照该发布版公布的校验和，再在目录内执行：

sha256sum -c SHA256SUMS

此命令校验 kit 内全部文件的完整性。在 lifecycle.py 的verify_kit中可以看到更严格的校验逻辑：校验和条目必须恰好覆盖PKGBUILD、README.md、SOURCE-PROVENANCE.json、lifecycle.py与源码归档五个文件，拒绝符号链接，且 runner 自身的字节必须与 kit 内lifecycle.py的校验和一致——防止"工具链被调包"。

用 makepkg 构建

在该目录中以普通用户身份运行makepkg。配方默认使用/usr/bin/g++；如果你的匹配编译器在其他位置，先设置环境变量再调用：

CUA_RELEASE_CXX=/absolute/path/to/g++ makepkg

选中的编译器会经过完整身份校验（见 verify.py）：

1. 校验pacman -Q hyprland恰为hyprland 0.56.2-1，pkg-config --modversion hyprland恰为0.56.2；
2. 通过宏展开校验 GCC 版本/日期字符串，并拒绝 Clang；
3. 用readelf -p .comment校验 Hyprland 合成器可执行文件的 ELF 注释包含GCC: (GNU) 16.1.1 20260728；
4. 编译一个探针对象文件，校验探针自身的.comment与合成器编译器一致（只信编译器自报版本不够，还要信它实际产出的字节）；
5. 解析编译器与合成器各自的libstdc++.so.6运行时并比对 SHA-256，两者必须解析到libstdc++.so.6.0.36的同一字节。

由 PKGBUILD.in 可知，构建启用CUA_HYPRLAND_INPUT=ON（生产输入），禁用实验性签名输入（CUA_HYPRLAND_TEST_INPUT=OFF）与输入追踪（CUA_HYPRLAND_INPUT_TRACE=OFF），并运行打包内置的 CTest 套件——即使传入--nocheck也无法产出未经测试的包，因为package()阶段同样强制执行测试。

安装到系统

安装或替换模块前，请保存工作并退出 Hyprland 桌面会话，在文本控制台（text console）执行：

package_file="$(makepkg --packagelist)" sudo pacman -U "$package_file"

安装产物落位：

安装没有install hooks、自动加载或配置变更。请保留包文件与其 provenance 以便回滚。

在一次性环境中验证软件包生命周期

门禁前置条件

lifecycle.py是独立的生命周期门禁，运行前需具备：可弃置的 Linux x86_64 Arch 环境、固定的原生依赖、makepkg、bsdtar、pacman、Python 3.11+、sudo。必须使用普通构建用户，并已配置sudo -n免密授权——门禁不会为交互式密码失败兜底，也不会自动安装缺失依赖。门禁使用配方的原生编译器、合成器与共享运行时检查执行构建与测试。

运行门禁

在全新、已验证的 kit 目录中，用清单中的值替换COMMIT_SHA与DRIVER_VERSION，NEW_EVIDENCE_DIRECTORY必须是不存在的路径：

python3 lifecycle.py --kit . --revision COMMIT_SHA \ --driver-version DRIVER_VERSION --output NEW_EVIDENCE_DIRECTORY

若编译器不在/usr/bin/g++，追加--cxx /absolute/path/to/g++。注意 lifecycle.py 的入口约束：必须是 Linux x86_64、普通用户（geteuid() != 0，只有隔离的 pacman 才允许 sudo）、编译器路径必须为绝对路径。由显式提交的 SHA 生成的开发 kit 也可以在发布前通过该门禁，但通过门禁不代表资产已发布。

门禁内部行为

门禁将 kit 复制进证据目录后执行makepkg，随后逐项断言：

• 包内容：精确核对模块、许可证、provenance 负载；拒绝配置文件与 install hooks（见 lifecycle.py 的package_payload，允许的负载集合固定为MODULE + SOURCE + BUILD + LICENSE）；
• 模块哈希：模块 SHA-256 必须与构建 provenance 一致，且模块、编译器的共享运行时 SHA-256 必须与合成器运行时一致；
• ALPM 事务：sudo pacman只使用新建的隔离文件系统根与数据库根、显式配置、禁用 scriptlets、空 hook 目录。对"安装 → 移除 → 重装"三个阶段的已安装字节与隔离的操作员配置哨兵逐次校验；
• 依赖拒绝（负向对照）：第二个 ALPM 根中放置不匹配版本的 Hyprland 依赖 fixture，包必须被拒绝并报出特定的hyprland=0.56.2-1依赖错误；匹配依赖的成功安装正是该拒绝的正向对照。

隔离根中的 Hyprland 与 GCC 运行时依赖是仅含元数据的 fixture，用于测试 ALPM 依赖解析而非执行这些依赖。运行器不会加载插件、不修改宿主桌面配置、不安装宿主包、不重启合成器，因此可以与其他正在进行的桌面验证并行。通过后写出RESULT.json，构建日志、事务日志、包与隔离根保留在证据目录供检查。

门禁的能力边界

该门禁不证明活激活、重启、升级或回滚。要完成这些门禁，须在既有桌面验证结束后，按下方"新鲜桌面会话"流程调度：保留旧包与匹配的原生环境，替换后重启并验证激活与输入，再以保存的旧包在另一个新鲜合成器上重复。发布版下载与校验和验证也需要单独的证据。

在全新桌面会话中激活输入

加载模块与查看状态

以固定合成器启动全新 Hyprland 会话后，显式加载模块并检查状态：

hyprctl plugin load /usr/lib/cua/hyprland/cua-hyprland-plugin.so hyprctl -j cua:status

cua:status命令由插件在 plugin.cpp 中注册（Socket1 API 下为精确匹配命令）。JSON 输出由 status.cpp 渲染，包含：

• protocol（协议主/次版本与最大帧字节）、compositor_epoch；
• abi.compiled_hash/abi.runtime_hash/abi.match——编译期 ABI 指纹与运行期哈希是否一致；
• configured（配置项是否启用）、transport.ready/transport.socket/transport.peer_policy（默认same_uid，socket 模式0600）；
• capabilities、connections各类计数（接受的连接、拒绝的对等方、繁忙拒绝、握手/空闲超时、畸形帧）。

ABI 指纹在 plugin.cpp 中由 Git 提交哈希与aquamarine、hyprutils、hyprgraphics、hyprcursor、hyprlang的去 patch 版本号拼接而成，PLUGIN_INIT时若与运行期 API 哈希不一致会直接抛错拒绝加载。

启用本地输入传输

本地输入传输默认关闭。启用后授予可信的本地桌面输入能力，Driver 仍会对单个调用执行自己的权限策略。Omarchy 的 Lua 配置中添加：

hl.config({plugin = {cua = {enabled = true}}})

传统 Hyprland 配置则添加：

plugin:cua:enabled = true

配置项在 plugin.cpp 中以CBoolValue注册（默认false）。修改配置后必须执行hyprctl reload，再查看hyprctl -j cua:status——仅运行时关键字或 Lua 求值而未经配置重载，不会协调（reconcile）输入 socket。请核对状态中的协议、能力、socket 路径与合成器身份；仅仅加载模块不能证明输入可用。

然后以启用 Wayland 输入的方式启动匹配的 Driver：

CUA_DRIVER_RS_ENABLE_WAYLAND=1 cua-driver ...

其生产输入协议默认为 v3。

输入路径的精确约束

输入路径校验确切的原生应用包：libreoffice-fresh 26.2.5-3（Calc）、inkscape 1.4.4-6，并要求规范evdev/pc105/us键盘映射——不允许变体、重映射或额外布局组。存在两条独立输入通道，第三个并发持有者会收到 lane-busy 拒绝。其他应用版本、Chromium/Electron 与 XWayland 均不在该输入契约之内。

操作后请使用常规 Driver 快照与后台动作验证应用结果——送达确认不等于目标编辑真实发生，不要自动重放部分或未知动作。发布版的 native evidence 会标识这些限制内的合格操作单元。

升级、回滚与移除

升级

升级前保留已安装包的副本及其确切的合成器/编译器/运行时 provenance。用新包声明的固定依赖构建并测试替换包；退出桌面会话，在文本控制台安装替换包，再启动全新桌面会话并重复激活与状态检查。不要通过热卸载/重载模块来替换：生产输入会保留资源直到合成器进程退出。

回滚

若替换包验证失败：退出桌面会话，用pacman -U配合精确的已保存包文件名重装旧包，恢复其匹配的合成器/运行时环境，再启动全新会话。不要绕过精确的 Hyprland 依赖强制安装。若匹配的固定依赖不可得，就让插件保持未激活，使用不带本插件的 Driver。

禁用与移除

要禁用输入：移除启用配置或将plugin:cua:enabled设为false，然后hyprctl reload。要移除软件包：先移除操作员添加的 plugin load / 启用配置，退出桌面会话，在文本控制台执行：

sudo pacman -R cua-hyprland-plugin

之后启动全新会话。在运行中的合成器内卸载、升级或删除文件不能替代重启合成器。

发布包验证链总结

整个发布流程形成一条"审核配方 → 确定性归档 → 原生 ABI 校验构建 → 隔离 ALPM 生命周期 → 新鲜会话激活 → 升级/回滚"的验证链，每环的证据边界在 USAGE.md 与 release/README.md 中均有明确声明：

如需继续深入，可查看 hyprland-plugin/README.md、protocol/cua-input-v3.md（输入协议）、tests/README.md（原生证据脚本）与 packaging/arch/PKGBUILD（仅供发现的本地配方）。按本文流程，即可在受控环境中安全地构建、验证并运维 Cua 的 Hyprland 生产输入插件。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua