让每一次点击、拖拽、滚轮都看得见。
跨平台桌面输入反馈引擎 · 可扩展 · 可插件化 · 支持 WASM
📦 下载 · 📖 文档 · 🐛 反馈 · 🤝 参与贡献 · ⭐ Star
🇨🇳 中文 | 🇬🇧 English
鼠标伴宠 — 不只是特效展示，也是项目持续演进的重要能力方向
- 🎯 五条独立效果通道 — 点击、拖尾、滚轮、长按、悬停，不是换皮，而是独立能力面
- 🔌 WASM 插件运行时 — 用 WASM 编写自己的效果和指示器，宿主控制渲染边界，插件只做逻辑
- ⌨️ 输入指示器 — 鼠标点击、滚轮方向、键盘组合键可视化，
Cmd+Tab、W+ x3一目了然 - 🤖 自动化映射 — 鼠标动作、滚轮、手势映射到快捷键注入，不只是看起来酷，还有生产力
- 🐾 鼠标伴宠 — 插件优先的 Mouse Companion 路线，跟随光标的跨平台桌面宠物
- 🌐 统一设置面 — Web 设置界面跨平台共享，配置路径统一、状态同步、可调可回退
适合做录屏、教程、直播演示的创作者，也适合想在 C++ 宿主里引入 WASM 扩展的开发者。
 点击波纹 |
 粒子拖尾 |
 滚轮反馈 |
 长按蓄力 |
 悬停光晕 |
鼠标伴宠 |
统一的 Web 设置界面 — 跨平台共享，所有配置一站搞定
 输入指示器 |
 自动化映射 |
- 输入指示器 — 把鼠标点击、滚轮方向、键盘组合键一起展示出来，
L x2、W+ x3、Cmd+Tab这类信息在录屏和演示里更直观 - 自动化映射 — 支持把鼠标动作、滚轮和手势映射到快捷键注入，让输入反馈进一步进入效率工作流
展开看这两块更适合哪些场景
- 录屏 / 教程 / 直播：观众不仅能看到鼠标在哪，也能知道你到底按了什么、切了什么、触发了什么
- 效率工具 / 桌面增强：手势和输入映射不只是展示层，而是可以进一步参与真实操作流程
项目正在积极建设中，有很多方向等你参与！
| 方向 | 说明 | 入口 |
|---|---|---|
| 🎨 新视觉效果 | 新的点击、拖尾、悬停样式设计 | 效果文档 |
| 🔌 WASM 插件 | 编写新插件或完善工具链 | 插件模板 |
| 🖥️ 跨平台对齐 | Windows / macOS 行为一致性 | Issue Tracker |
| 🌐 WebSettings | 设置页体验优化 | WebUI 源码 |
| 🐾 鼠标伴宠 | 鼠标伴宠动画、交互与插件化 | 鼠标伴宠路线图 |
| 📝 文档与测试 | 文档完善、自检脚本、回归工具 | Docs |
推荐流程：
- 先开一个 Issue 说明想法
- 简单讨论确认方向
- 提交 PR
- 大改动或架构讨论，建议先邮件联系
📮 联系邮箱： ksun22515@gmail.com
# 推荐：Visual Studio 2026 打开 MFCMouseEffect.slnx，Release | x64 编译运行
# 或使用封装命令
.\mfx.cmd build # 默认 Release | x64
.\mfx.cmd build --shipping # 精简发行构建
.\mfx.cmd package # 生成安装包./mfx build # 仅编译当前宿主
./mfx build --skip-webui-build # 跳过 WebUIWorkspace 重编译
./mfx run # 编译并启动
./mfx run-no-build # 跳过编译直接运行
./mfx run-no-build --seconds 30 # 自动退出，快速验证
./mfx package # 打包
⚠️ macOS 需要授予 Accessibility 和 Input Monitoring 权限才能捕获全局输入。
| 平台 | 状态 | 说明 |
|---|---|---|
| Windows 10+ | ✅ 稳定主线 | 能力最完整，保持兼容回归 |
| macOS | 🔥 主开发线 | 当前优先投入方向 |
| Linux | 🔄 跟随线 | 编译门禁与合同回归 |
当前节奏：
macOS mainline first，同时要求 Windows 行为不回退。
📦 核心架构亮点（展开查看）
- 宿主控制渲染边界 — 插件只做逻辑计算，宿主拥有渲染执行、预算校验、回退与资源控制
- 模块分层清晰 — Core / Platform / Server / WebUI / Tools / Docs 各自职责独立
- 渐进式扩展 — 内建效果可用，WASM 插件可叠加，原生回退可兜底
- 跨平台语义对齐 — Win/mac 共用核心语义与设置面，减少平台行为漂移
- 可观测性内建 — WebSettings、诊断、回归脚本、自检入口是一起设计的
- 支持
effects/indicator双 surface - manifest 加载、重载、导入、导出
- 预算控制、命令校验、错误码、阶段诊断
- transient 与 retained 两类渲染语义
- 丰富的命令原语：
spawn_text/spawn_image/spawn_pulse/spawn_polyline/spawn_ribbon_strip/spawn_glow_batch等
插件快速入口：
📂 项目结构（展开查看）
MFCMouseEffect/
├── MFCMouseEffect/
│ ├── MouseFx/ # Core：特效、自动化、WASM、诊断、服务
│ ├── Platform/ # Windows / macOS / Linux 平台实现
│ ├── WebUIWorkspace/ # Svelte 设置页源码
│ ├── Runtime/ # 运行时资源与依赖
│ ├── Assets/ # Companion / 视觉资源
│ └── WasmRuntimeBridge/ # WASM 运行时桥接
├── tools/
│ ├── platform/regression/ # 回归脚本
│ ├── platform/manual/ # 手测 / 自检脚本
│ └── docs/ # 文档索引与治理脚本
├── docs/ # 架构、路线图、问题、回归文档
├── examples/ # 示例与模板
└── mfx / mfx.cmd # 推荐命令入口
❓ 常见问题（展开查看）
检查系统权限：Accessibility + Input Monitoring。缺失时会进入 degraded 状态，恢复权限后无需重启。
稳定性考虑，默认 --no-gpu。需要 GPU 路线请使用 ./mfx build --gpu。
Shipping 保留主运行时与 WebUI，但裁掉深度测试和重诊断能力，更适合交付。
很多设置项是后端状态驱动的。如果后端绑定未生效，页面会按真实状态回写。优先检查插件 manifest 路径和 lane 状态。
当前 macOS 包未签名。可能被 Gatekeeper 拦截，在 Finder 中右键 Open 完成首次放行。
🧪 回归与自检（展开查看）
# 全量 POSIX 套件
./tools/platform/regression/run-posix-regression-suite.sh --platform auto
# Effects 聚焦回归
./tools/platform/regression/run-posix-effects-regression-suite.sh --platform auto
# Automation 合同回归
./tools/platform/regression/run-posix-core-automation-contract-regression.sh --platform auto
# WASM 聚焦回归
./tools/platform/regression/run-posix-wasm-regression-suite.sh --platform auto📖 文档入口（展开查看）
- 文档总览：docs/README.zh-CN.md
- English docs：docs/README.md
- macOS 主线快照：docs/refactoring/phase-roadmap-macos-m1-status.md
- P2 能力索引：docs/agent-context/p2-capability-index.md
本项目基于 MIT License 开源。你可以自由使用、修改和分发，但请保留协议与版权声明。
觉得有用？请点个 Star ⭐
也欢迎在 Issues 和 Discussions 留言反馈