BetterZUIKey v1.3.0-beta3

BetterZUIKey v1.3.0-beta3

Please scroll down for English / 英语请向下滚动

更新

• 脚本行尾修复：执行「执行命令…」脚本前自动去除 \r（等效 dos2unix），修复 Windows/CRLF 的脚本在设备 shell 下异常的问题；内置脚本模板已转为 LF。
• 移除 Ctrl+Space 双投递：删除快捷键 Tab 中的 Ctrl+Space 卡片及遗留代码（输入法增强仍可用）

---

BetterZUIKey v1.3.0-beta3

Update

• Script line endings: Strip \r before running custom scripts (dos2unix-style), fixing CRLF templates on device shell; bundled templates use LF.
• Script editor: Yellow warning when CRLF is detected — will convert to LF on run.
• Removed Ctrl+Space dual-delivery: Remove the Ctrl+Space card and legacy code in the tab for shortcut keys (input method enhancement is still available)

BetterZUIKey v1.3.0-beta2

更新

• 移除从未生效的弃用功能「OneVision 特性」开关，并同步更新帮助文档与 README。

Update

• Removed the unused deprecated OneVision Feature toggle; help docs and README updated accordingly.

Full Changelog: v1.3.0-beta1...v1.3.0-beta2

BetterZUIKey v1.3.0-beta1

BetterZUIKey v1.3.0-beta1

Please scroll down for English / 英语请向下滚动

摘要

这是第一个“稳定的”测试版 :)

本次更新兼具架构重构与新功能引入。模块全面接管 Meta 键行为（开始菜单、语音助手、输入法切换），不再依赖 ZUI 区域覆写控制；新增输入法增强设置页，切换输入法/语言各绑定一个物理组合键；IME 适配器改为 JSON profile 预设策略。后续迭代补充智能键 / Win 长按自定义命令、Win 组合键误触修复与国行语音助手适配。

要查看自上次发布以来的完整更改，请参阅：v1.1.0-beta1...v1.3.0-beta1

🚀 新功能

• Win/Meta 键路由：短按 → 开始菜单，长按 → 语音助手。非特定键盘固件（scanCode≠787345）由模块接管长按计时。
• 输入法增强：新增设置页，切换输入法/切换语言各自绑定一个物理组合键（Ctrl+Shift / Alt+Shift / Ctrl+Space / 右 Alt / Win 长按），替代旧版分散的区域覆写配置。
• IME profile 系统：JSON 配置支持 framework / hook / keyremap 三种策略，自动匹配当前输入法执行切换（详见内置帮助文档）。
• 智能键 507 / 508：三档模式（跟随系统 / 忽略 / 执行命令…）。跟随系统时短按、长按均透传 ZUI；忽略时无动作；**执行命令…**时短按运行脚本、长按打开命令编辑器。长按卡片跳转系统「键盘应用功能」设置页。
• Win 长按：四档模式（保持默认=透传由系统决定 / 启用 ZUX=模块接管语音助手 / 忽略 / 执行命令…）；非 787345 键盘仅在「启用 ZUX」或「执行命令…」时由模块计时；长按卡片（执行命令模式下）打开命令编辑器。
• Termux 集成：设置页提供 Termux 权限一键授予（RUN_COMMAND 等）；脚本模板支持 root / 超时 / 单例运行选项。

🐛 修复

• Win 组合键误触开始菜单：使用 Win+D 等组合键后，Meta 松开时不再误弹开始菜单（会话内 winComboUsed 跟踪，与 Fn 映射共用抑制逻辑）。
• 国行语音助手：PRC 设备 Win 长按优先调用 launchXiaoTianAgent()，修复仅日志成功但助手 UI 不弹出的问题。
• 键盘检测页：检测期间不再误触 ZUI / 系统快捷键。

⚠️ 行为变更

• Win 短按覆写（overrideMetaSingle）移除"关闭（透传）"选项，旧配置 OFF → BLOCK 迁移。Meta 状态机已承担开始菜单 / 语音助手 / IME 切换 / Fn 修饰四重职责，继续叠加透传会进一步复杂化。且实测注入后多数 App 无法识别（含 Windows APP、ToDesk、SpaceDesk 等远控场景），收益极低。
• 不再模块接管多数 ZUI 物理键：快捷键列表移除静音、触控板、分屏、搜索、设置、Fn 锁定、背光、Print Screen 截图、超级互联、键盘恢复/翻转等覆写项；上述按键交由 ZUI / 系统原生处理。模块仅保留 507 / 508 智能键覆写（及 Win/Meta 路由等既有能力）。
• 智能键：覆写模式迁移为 AppKeyMode（跟随系统 / 忽略 / 执行命令…）。Win 长按保留 OverrideMode（保持默认 / 启用 ZUX / 忽略）并新增 winLongUseCommand 执行命令；旧 overrideWinLongPress / app*LongPressOverride 加载时自动迁移。

🔧 其他

• 删除 A15/A16 上已失效的备用开始菜单路径
• 移除 RegionHook、regionOverride/countryOverride 等区域覆写字段，改由增强页统一管理
• 快捷键列表 UI 与字符串调整；模板编辑器、ConfigResolver 随 Config 字段变更同步
• 应用内语言切换与 locales_config 完善；帮助文档更新 507/508 / Win 长按说明

---

BetterZUIKey v1.3.0-beta1

Highlights

This is the first stable beta release :)

This update combines architectural refactoring with new feature additions. The module now fully handles Meta key behavior (Start Menu, voice assistant, IME switching), no longer relying on ZUI region-based overrides; a new IME Enhancement settings page lets you bind a physical key combo for IME switching and language switching respectively; IME adapters are now JSON profile presets. Follow-up work adds smart-key / Win long-press custom commands, Win combo Start Menu fix, and PRC voice assistant support.

For a complete list of changes since the last release, see: v1.1.0-beta1...v1.3.0-beta1

🚀 New Features

• Win/Meta key routing: Short-press → Start Menu, long-press → voice assistant. For keyboards without the specific firmware scanCode (≠787345), the module manages the long-press timer independently.
• IME Enhancement: New settings page — IME switching and language switching each bind to a physical key combo (Ctrl+Shift / Alt+Shift / Ctrl+Space / Right Alt / Win long-press), replacing the old scattered region-override configuration.
• IME profile system: JSON-configurable with three strategies (framework / hook / keyremap), auto-matching the current IME to execute switching (see built-in help docs for details).
• Smart keys 507 / 508: Three modes (Follow system / Block / Run command…). Follow system: short and long pass through to ZUI. Block: no action. Run command…: short press runs script, long press opens command editor. Long-press card opens system keyboard shortcut settings.
• Win long-press: Four modes — Keep default (pass-through, system decides), Use ZUX (module voice assistant), Block, Run command…; module timer on non-787345 keyboards only for Use ZUX / Run command…; long-press card opens command editor in Run command mode.
• Termux integration: One-tap Termux permission grant in Settings (RUN_COMMAND, etc.); script templates support root / timeout / singleton options.

🐛 Fixes

• Spurious Start Menu after Win combos: Meta UP no longer opens Start Menu after Win+D and other combos (winComboUsed session tracking, shared with Fn-map suppression).
• PRC voice assistant: Win long-press on PRC devices prefers launchXiaoTianAgent(), fixing cases where logs showed success but the assistant UI never appeared.
• Keyboard detect page: No longer triggers ZUI / system shortcuts while detecting keys.

⚠️ Behavioral Changes

• Win short-press override (overrideMetaSingle): Removed "Off (passthrough)" option. Old configs with OFF are migrated to BLOCK. The Meta state machine already handles four responsibilities (Start Menu / voice assistant / IME switching / Fn modifier); adding passthrough injection would further complicate it. Moreover, injected Meta events are unrecognized by most apps in practice (including Windows APP, ToDesk, SpaceDesk, and other remote desktop scenarios), yielding negligible benefit.
• No module override for most ZUI physical keys: Removed shortcut cards for mute, touchpad, split-screen, search, Settings, Fn-lock, backlight, Print Screen, SuperConnect, keyboard restore/flip, etc. These keys are handled by ZUI / the system natively. Module overrides remain for 507 / 508 smart keys only (plus existing Win/Meta routing).
• Smart keys: Override migrated to AppKeyMode (Follow system / Block / Run command…). Win long-press keeps OverrideMode (Keep default / Use ZUX / Block) plus winLongUseCommand for scripts; legacy overrideWinLongPress / app*LongPressOverride auto-migrate on load.

🔧 Other

• Removed obsolete Start Menu fallback paths from A15/A16
• Removed RegionHook, regionOverride/countryOverride and other region-override fields, now consolidated under the IME Enhancement page
• Shortcut list UI and string adjustments; template editor and ConfigResolver synced with Config changes
• In-app locale switching and locales_config improvements; help docs updated for 507/508 and Win long-press

v1.2.0-beta1 Pre-release

BetterZUIKey v1.2.0-beta1

Please scroll down for English / 英语请向下滚动

摘要

本次更新核心目标是消除 Root 依赖：即使没有授予 Root 权限，模块的各项功能也能正常工作——写入系统设置、打开 LSPosed 管理器、检测键盘重映射等操作现在通过系统级代理自动完成，仅会产生约 1~2 秒的轻微延迟。同时修复了上一版本遗留的多个问题，清理了冗余代码。

要查看自上次发布以来的完整更改，请参阅：v1.1.0-beta1...v1.2.0-beta1

🚀 新功能

• 无需 Root 也能用：绝大部分原本需要直接 Root 的操作现在有了降级方案
  • 修改快捷键开关时，若无法直接写入系统设置，会自动通过系统进程代理写入
  • 打开 LSPosed 管理器、授予 Secure 权限均支持自动降级
  • ESC→BACK 重映射检测不再强制依赖 Root
  • 首页状态指示改为"部分操作会稍有延迟"
• 安全保护：代理 IPC 的快捷键的写入请求加入了白名单校验，异常写入会触发红色告警
• 提示优化：AOSP 辅助键首次操作缺少权限时，弹出提示卡片，可直接尝试自动代理授权或复制命令手动执行

🐛 修复

• Ctrl 长按开关：修复了开关在写入后无法正确显示状态的问题
• 写入失败还原：无法写入时，开关会自动弹回原位，不再出现状态不一致
• 权限检查：不再因检查权限而意外修改系统设置
• 首页状态：修复了重启后偶尔误报"作用域错误"的问题
• 多项内部健壮性修复（空指针保护、异常兜底、内存泄漏防护等）

🔧 其他

• 删除了已被快捷键 Tab 替代的独立 AOSP 辅助键页面
• 代理操作的等待时长约为 1.5 秒
• 帮助文档中英文同步

📝 已知问题

上个版本报告的问题仍然存在：

• Meta 短按关闭：覆写为"关闭"后，短按 Meta 需要长按才能发送事件，暂未定位原因
• 输入法切换整合（Ctrl+Shift 重映射等）的图形界面尚未完成
• Ctrl+Space 双投递（同时发给输入法和应用）尚未完整实现

---

BetterZUIKey v1.2.0-beta1

Highlights

This update aims to eliminate root dependency: even without root access, all module features work normally — writing system settings, opening the LSPosed manager, detecting keyboard remapping, etc. are now handled automatically through a system-level proxy, with only a minor ~1–2 second delay. Several issues from the previous version are also fixed and redundant code has been cleaned up.

For a complete list of changes since the last release, see: v1.1.0-beta1...v1.2.0-beta1

🚀 New Features

• Works without Root: Most operations that previously required root now have fallback paths

  • Shortcut switch writes are proxied through the system process when direct write fails
  • Opening LSPosed manager and granting Secure permissions support automatic fallback
  • ESC→BACK remapping detection no longer requires root
  • Home page status now reads "some writes may be slightly delayed" instead of warning colors

• Security: Write requests are validated against a whitelist; suspicious writes trigger a red alert

• Better Prompts: When AOSP accessibility keys are first used without the required permission, a prompt card appears offering auto-grant via proxy or manual command copy

🐛 Fixes

• Ctrl Long-Press Switch: Fixed switch state not updating correctly after async write
• Write Failure Revert: Switches now automatically revert on write failure, eliminating UI/state mismatch
• Permission Check: No longer accidentally modifies system settings during permission check
• Home Status: Fixed occasional false "wrong scope" alerts after reboot
• Various internal robustness fixes (null guards, exception handling, memory leak prevention)

🔧 Other

• Removed standalone AOSP accessibility page (superseded by Shortcuts tab)
• Proxy operations complete in ~1.5 seconds
• Help docs synced (EN ↔ ZH)

📝 Known Issues

Issues reported in the previous version remain:

• Meta short-press Off: When Meta is overridden to "Off", short-pressing Meta requires a long press to send events. Root cause not yet identified.
• IME switching integration (Ctrl+Shift remap etc.) GUI not yet complete
• Ctrl+Space dual delivery (IME + app) not fully implemented

v1.1.0-beta1 Pre-release

BetterZUIKey v1.1.0-beta1

Please scroll down for English / 英语请向下滚动

摘要

本次更新侧重稳定性和兼容性，主要处理了 Fn 总开关失效、Alt+Tab 覆写失败、Meta 键无法透传等残留问题，响应 LSPosed 的建议迁移至 libxposed API 101（LSPosed 2.0.x+），增强了模块加载检查，初步尝试引入输入法适配器系统，并引入了快捷键搜索与过滤、模板拖拽排序、自动刷新等多项新特性。

要查看自上次发布以来的完整更改，请参阅：v1.0...v1.1.0-beta1

⚠️ 重大迁移

• 迁移至 libxposed API 101：从旧版 Xposed API 82 迁移至 libxposed 101，兼容 LSPosed 2.0.x+，不再支持旧版 Xposed 框架。
  • 应该没人用这个老东西了吧

🚀 新功能

• 快捷键设置重组：按照逻辑重新排列了快捷键的摆放顺序，增加了搜索和多选框过滤（开关状态 + 覆写模式）的支持

• 模板管理：模板编辑器做出如下调整

  • AND 分词搜索：允许使用关键词搜索，结果必须同时命中所有关键词
  • 支持复制、重命名模板：现在可以创建模板的副本，在新建和重命名模板时有更完善的名称检查
  • 调整排序：可以拖拽或者使用按钮重新排序，在上面的模板优先生效

• 模块状态：增强了模块状态的检查，在主页模块状态的部分具体如下

  • **🔴 红色：**模块没有激活
  • 🟠橙色：模块被激活，但选择了错误的作用域
  • 🟡黄色：模块被激活，但缺少 root 权限
  • 🟢绿色：模块正确激活，且授予了 root 权限

• 自动刷新：现在，在进入可刷新的页面后，BetterZUIKey 会自动刷新以同步状态了

• 更准确的键盘映射：Fn 设置页自动检测系统级 ESC→BACK 重映射，并提供配置指引

  • 如果开启了 ESC→BACK，可能会产生冲突，需要自行生成配置

• Ctrl+Shift → Ctrl+Space 重映射：可选的按键重映射，Ctrl+Space 同时投喂输入法（切语言）和应用（代码补全）

  • 尚未完成 UI 界面。

• 输入法适配器系统：动态加载 .dex/.jar 输入法适配器，支持运行时扩展输入法行为。包含 GenericIMEAdapter 模板和 Ctrl+Space 注入通道

  • 尚未完成 UI 界面。

• 应用图标：微调了图标。

• 其它调整：部分布局和尺寸的微调或统一，以利于用户阅读和操作

🐛 修复

• Fn 开关失效：无法通过开关控制虚拟 Fn 的行为

  • 修复了热重载后 Fn 总开关/Toast开关引用过时的问题。

• Alt+Tab 覆写：“关闭”模式下 Alt+Tab 仍然触发切换器

  • 增加 L0+L1 双层 stripAltMeta 阻止 ZUI 和 AOSP 应用切换器触发，让物理 Tab 事件正确到达前台应用

• Meta 键覆写：“关闭”模式下 Meta 键无法抵达应用

  • 修复 Meta 键注入的 scanCode 防反馈循环守卫；L1/L3/L4 三层拦截 ZUI/AOSP type=21

• Fn 组合键修饰键：带有修饰的 Fn 键无法正确透传

  • Fn 组合键现允许辅助修饰键透传（如 Win+Alt+F-key → Alt+F-key）

• Ctrl+/ 快捷键：修复 Ctrl 长按开关与 Ctrl+/ 覆写模式之间的联动问题。

  • 现在调整 Ctrl+/ 的覆写行为时，不再会自动关闭 Ctrl 长按开关了

🔧 内部变更

• 新增 HookCompat.java 兼容层桥接新旧 Xposed API
• LogHelper 统一为 android.util.Log
• 添加 libxposed XposedModule 子类的最小 ProGuard keep 规则
• MainHook 生命周期重构（onSystemServerStarting / onPackageReady）
• ConfigIPCManager 启动标记 IPC 延迟重试（5s 间隔，最长 1min）
• 首页/全局页增加了 Refreshable 接口
• 调整 GitHub Actions CI，现有行为：
  • dev 分支下，自动构建 [Nightly] 开头的提交
  • main 分支下，仅发布时自动构建

📝 已知问题

• 输入法切换整合 待完成
  • GUI 仍为零散的快捷键配置
• Ctrl+Space 双投递 未完整实现
  • Binder 直达通道未完成
• “短按” Meta 被覆写为“关闭”时需要长按才能发送事件
  • 暂未完全定位问题，亦未找到解决方案

---

BetterZUIKey v1.1.0-beta1

Highlights

This update focuses on stability and compatibility, primarily addressing residual issues such as the Fn master switch failure, Alt+Tab override failure, and Meta key passthrough failure. In response to LSPosed's recommendation, the module has been migrated to libxposed API 101 (LSPosed 2.0.x+). Module loading checks have been enhanced, an initial IME adapter system has been introduced, and several new features have been added including shortcut search & filtering, template drag-to-reorder, and automatic refresh.

For a complete list of changes since the last release, see: v1.0...v1.1.0-beta1

⚠️ Breaking Migration

• Migration to libxposed API 101: Migrated from legacy Xposed API 82 to libxposed 101, compatible with LSPosed 2.0.x+. Legacy Xposed frameworks are no longer supported.
  • Anyone still using this old stuff?

🚀 New Features

• Shortcut Settings Reorganized: Logically reordered shortcut placement, added search and multi-checkbox filtering support (toggle state + override mode)

• Template Management: The template editor has been adjusted as follows:

  • AND-based keyword search: Search with keywords where results must match all keywords simultaneously
  • Copy & rename templates: Templates can now be duplicated; more robust name validation when creating or renaming templates
  • Adjustable ordering: Reorder by dragging or using buttons — templates higher in the list take priority

• Module Status: Enhanced module status checks, displayed on the Home page module status section:

  • 🔴 Red: Module is inactive
  • 🟠 Orange: Module is active, but incorrect scope is selected
  • 🟡 Yellow: Module is active, but root permission is missing
  • 🟢 Green: Module is correctly active with root permission granted

• Auto Refresh: BetterZUIKey now automatically refreshes to sync status when entering a refreshable page

• More Accurate Keyboard Mapping: The Fn settings page now auto-detects system-level ESC→BACK remapping and provides configuration guidance

  • If ESC→BACK is enabled, conflicts may occur, requiring custom configuration

• Ctrl+Shift → Ctrl+Space Remapping: Optional key remapping — Ctrl+Space feeds both the IME (language switching) and the app (code completion)

  • UI not yet complete.

• IME Adapter System: Dynamically load .dex/.jar IME adapters, supporting runtime extension of IME behavior. Includes GenericIMEAdapter template and Ctrl+Space injection channel

  • UI not yet complete.

• App Icon: Minor icon adjustments.

• Other Adjustments: Various layout and sizing tweaks or unifications for improved readability and usability

🐛 Fixes

• Fn Switch Broken: Unable to control virtual Fn behavior via the toggle

  • Fixed stale references for the Fn master switch / Toast switch after hot reload.

• Alt+Tab Override: Alt+Tab still triggered the app switcher in "Off" mode

  • Added L0+L1 dual-layer stripAltMeta to prevent ZUI and AOSP app switcher activation, allowing physical Tab events to reach the foreground app correctly

• Meta Key Passthrough: Meta key could not reach apps in "Off" mode

  • Fixed Meta key injection scanCode anti-feedback-loop guard; L1/L3/L4 triple-layer interception of ZUI/AOSP type=21

• Fn Combo Modifiers: Fn combos with modifiers failed to passthrough correctly

  • Fn combos now allow auxiliary modifier passthrough (e.g., Win+Alt+F-key → Alt+F-key)

• Ctrl+/ Shortcut: Fixed the coupling between Ctrl long-press toggle and Ctrl+/ override mode.

  • Adjusting the Ctrl+/ override behavior no longer automatically turns off the Ctrl long-press toggle

🔧 Internal Changes

• Added HookCompat.java compatibility layer bridging old and new Xposed APIs
• LogHelper unified to use android.util.Log
• Added minimal ProGuard keep rules for libxposed XposedModule subclasses
• MainHook lifecycle refactored (onSystemServerStarting / onPackageReady)
• ConfigIPCManager startup marker IPC with delayed retry (5s interval, up to 1 min)
• Added Refreshable interface for Home and Global pages
• Adjusted GitHub Actions CI, current behavior:
  • On dev branch: auto-build commits starting with [Nightly]
  • On main branch: build only on release

📝 Known Issues

• IME switching integration pending completion
  • GUI remains as fragmented shortcut configuration
• Ctrl+Space dual delivery not fully implemented
  • Binder direct channel not yet complete
• "Short-press" Meta overridden to "Off" requires long press to send events
  • Root cause not yet fully identified, nor solution found

v1.0 Pre-release

第一个测试版，大概率会有Bug

PS：输入法相关的工作任重道远，需要更长时间完成适配和UI制作，目前相关功能基本是无效的

---

The first preview version, thus high probability of bugs.

PS: The work related to IME adaptation is a long process. Currently, all function related are almost all ineffective.