支持五类核心交互通道：

• click：点击波纹、点击文本、点击图片等
• trail：拖尾、粒子、线段连续轨迹
• scroll：滚轮方向与节奏反馈
• hold：长按蓄力、环形进度、持续态反馈
• hover：悬停视觉响应

亮点：

• 五条通道是独立能力面，不是单一路径的样式切换
• Win/mac 在类型归一化、配置映射和语义层面持续对齐
• 可通过 WebSettings 调整类型、参数和行为
• 部分效果支持 WASM 插件承接，而不是只能走内建实现

除了点击和拖尾，这个项目还支持独立的光标装饰层：

• 原生 ring / orb 装饰
• 独立于五条主特效通道存在
• 支持走内建路线，也支持切到 cursor_decoration WASM lane
• 会与应用黑名单、原生回退、插件启停保持一致的可控行为

输入指示器支持：

• 鼠标左键 / 右键 / 中键状态
• 滚轮方向与连击语义，例如 W+ x2
• 键盘事件与组合键标签，例如 Cmd+Tab
• 相对 / 绝对定位、多屏目标定位、偏移配置
• 原生 fallback 与 WASM indicator surface 双路线

自动化映射不是简单热键表，而是完整输入触发层：

• 鼠标动作映射：左/右/中键、滚轮上/下
• 鼠标手势映射：方向链，如 up_right、down_left_up
• 可配置手势触发键、采样步长、最小轨迹距离、最大方向段数
• 支持应用作用域匹配和确定性优先级规则
• 提供手势绘制、保存、自检与回归脚本

WASM 路线是这个项目最有辨识度的部分之一：

• 支持 effects 与 indicator 两类 surface
• 支持 manifest 加载、重载、导入、导出
• 支持预算控制、命令校验、错误码与阶段诊断
• 支持 transient 与 retained 两类渲染语义
• 宿主拥有渲染执行权，插件不直接控制窗口和资源

当前命令面已经覆盖很多高价值原语：

• spawn_text
• spawn_image
• spawn_pulse
• spawn_polyline
• spawn_path_stroke
• spawn_path_fill
• spawn_ribbon_strip
• spawn_glow_batch
• spawn_sprite_batch
• spawn_quad_batch
• retained emitter / trail / quad field / group primitives

项目内已经形成独立插件管理能力：

• 统一 Plugin Management 入口
• 支持 effect lane、indicator lane、cursor decoration lane 的策略绑定
• 支持插件 manifest 路径、启停、错误状态和回退状态观察
• 设置页能反映真实后端状态，而不是只改前端表单

插件是核心能力之一，建议直接从以下入口上手：

• 使用模板：examples/wasm-plugin-template/README.md
• 主文档：docs/architecture/custom-effects-wasm-route.zh-CN.md
• ABI 说明：docs/architecture/wasm-plugin-abi-v3-design.zh-CN.md
• 加载入口：设置页 Plugin Management -> 选择 manifest -> Apply

Mouse Companion 是当前非常有潜力的一条扩展路线：

• 目标是插件优先、跨平台可演进的桌面 companion 能力
• macOS 已有 Phase1 visual host
• Windows 当前是 Phase1.5，强调插件宿主、renderer seam 与可诊断 runtime
• 当前主线不是“随便做个宠物动画”，而是建立长期可扩展的 companion 架构

当前设置页按能力拆分，结构更清晰：

• General
• Mouse Companion
• Cursor Effects
• Input Indicator
• Automation Mapping
• Plugin Management

优点：

• 配置路径统一
• 页面组织与后端状态同步
• 更适合做平台共享、能力扩展和调试诊断

下面这些位置你后面直接替换成图片即可，结构我已经先给你搭好了。

模块	当前展示	模块	当前展示
设置页		点击特效
拖尾特效		滚轮特效
长按特效		悬停特效

更多细节图（占位，可继续追加）

场景	细节图	场景	细节图
输入指示器		自动化映射
WASM 运行时		插件管理
光标装饰		Mouse Companion

这是最建议放进 README 的部分之一，能显著减少“装不上 / 跑不起来 / 看不到效果”的反馈成本。

先检查系统权限：

• Accessibility
• Input Monitoring

当前项目在 macOS 上依赖这两类权限来做全局输入捕获。缺失时，运行时会进入 degraded 状态，但权限恢复后无需强制重启即可恢复。

这是当前项目的明确策略：

• 默认 --no-gpu
• 这样更稳，也能减少额外运行时依赖
• 如需 GPU 路线，显式使用 ./mfx build --gpu

Shipping 会保留主运行时与 WebUI，但会裁掉一些测试/重诊断能力：

• 不包含 /api/test 深度测试路线
• 更适合交付
• 不适合做最深层调试与 proof 类验证

当前不是主体验平台。

Linux 目前更偏：

• 编译通过
• 合同不漂移
• 跟随主线保持结构一致

如果你要完整体验，优先建议 Windows 或 macOS。

这个项目很多设置项是“前端表单 + 后端真实状态”双向对齐的。
如果后端绑定没有真正生效，页面刷新后会按真实状态回写，不会假装成功。

这类情况通常优先检查：

• 插件 manifest 路径是否有效
• 对应 lane 是否启用
• 当前平台是否支持该路线
• 是否触发了 fallback

不是。

这是项目的关键架构边界：

• 插件负责逻辑计算
• 宿主负责渲染执行、预算校验、回退与资源控制

这个约束是刻意设计的，目的就是让扩展能力和稳定性可以长期共存。

这是当前阶段的已知使用说明，不算异常：

• 当前 macOS 包仍是未签名产物
• 第一次启动可能被 Gatekeeper 拦截
• 某些情况下需要在 Finder 中使用 Open 完成首次放行
• 当前打包流程还没有接入 notarization

MFCMouseEffect/
├── MFCMouseEffect/
│   ├── MouseFx/                 # Core: effects, automation, wasm, diagnostics, server
│   ├── Platform/                # Windows / macOS / Linux 平台实现
│   ├── WebUIWorkspace/          # Svelte 设置页源码
│   ├── Runtime/                 # 运行时资源与依赖
│   ├── Assets/                  # Companion / 视觉资源
│   └── WasmRuntimeBridge/       # WASM 运行时桥接
├── tools/
│   ├── platform/regression/     # 回归脚本
│   ├── platform/manual/         # 手测 / 自检脚本
│   └── docs/                    # 文档索引与治理脚本
├── docs/                        # 架构、路线图、问题、回归文档
├── examples/                    # 示例与模板
└── mfx / mfx.cmd                # 推荐命令入口

• MouseFx/Core 负责语义与能力抽象，不直接把平台细节塞进业务逻辑
• Platform/windows、Platform/macos、Platform/linux 明确拆分平台实现
• MouseFx/Server 与 WebUIWorkspace 组成统一设置页与 API 服务边界
• tools/platform/regression 与 tools/platform/manual 让功能具备持续验证能力
• docs 不是附属品，而是架构协作的一部分

• 文档总览：docs/README.zh-CN.md
• English docs index: docs/README.md
• 当前高优先级上下文：docs/agent-context/current.md
• macOS 主线快照：docs/refactoring/phase-roadmap-macos-m1-status.md
• P2 能力索引：docs/agent-context/p2-capability-index.md

欢迎 Issue、讨论、建议，也欢迎直接参与改进。

在提交较大的功能、架构调整、跨平台行为变更之前，建议先联系确认方向，避免大家在不同假设上重复投入。

推荐方式：

• 先开 Issue 说明问题或想法
• 再提交 PR
• 大改动、能力扩张、架构路线讨论，建议先邮件沟通

联系邮箱：

• [email protected]

建议贡献方向：

• 新效果与新样式
• WebSettings 体验优化
• WASM 插件样例与工具链
• macOS / Windows 行为对齐
• 文档、测试、自检与回归脚本完善