[学习工作] Macim — 系统级键盘交互平台
社区发帖字段
- 标签：
学习工作- 标题：
学习工作赛道 Macim — 系统级键盘交互平台
一、Demo 简介
Macim 是一款 macOS 系统级键盘交互平台（App），让双手不再离开键盘——用一套统一的键盘流体验完成所有原本依赖鼠标的操作。
形态
- 平台：macOS 12+（Monterey 及以上）
- 技术栈：Swift 5.7+ / AppKit / Accessibility API / CGEventTap / Swift Concurrency
- 形态：本地 App，无后端依赖，单机运行
- 当前阶段：已实现 Hint Mode 主线（F1-F3.1），Grid/Scroll 在规划中
面向谁
- 开发者：IDE 频繁切换菜单、终端、文件树，每次手部切换都打断心流
- 写作者：长文本创作中既要鼠标点工具栏又要回键盘输入
- 数据分析师：表格、SQL 客户端、BI 工具中密集小按钮难以精准点击
- 无障碍用户：肢体障碍用户需要纯键盘完成所有操作
主要功能
| 能力 | 简介 |
|---|---|
| Hint Mode | 激活后为屏幕上每个可交互元素分配键盘标签（如 sa、sd），输入标签字符即可「点击」对应元素 |
| Grid Mode | 将屏幕划分为 3×3 网格，按 Q/W/E/A/S/D/Z/X/C 选择区域，可递归细分到像素级 |
| Scroll Mode | Vim 风格滚动，j/k 上下行、d/u 半页、gg/G 跳顶底 |
| Hint+Grid 混合 | Hint 扫描为空时自动回退到 Grid，覆盖 Canvas/Electron/OpenGL 等场景 |
二、创作思路
灵感来源
我是一名重度键盘用户，每天在 IDE、终端、笔记应用之间反复切换。每次伸手去摸鼠标都是一次上下文切换——不仅是物理上的，更是认知上的：
- 键盘 → 鼠标 → 键盘，每次切换平均耗时 2-3 秒
- 密集菜单中精准点击小按钮耗时且易错
- 相同的点击序列每天重复 300+ 次，没有任何统一方式去自动化
Vimac、Shortcat、Homerow 这些工具解决了一部分问题，但都有明显短板：Vimac 停更、Shortcat 无 Grid、Homerow 不支持混合模式。我意识到这不是「再做一个 Vimac」的问题，而是要做一个统一的键盘交互平台。
想解决的问题
| 痛点 | 现状 | Macim 的解法 |
|---|---|---|
| 频繁手部切换 | 每天 300+ 次键盘↔鼠标切换 | Hint 标签点击：键入 2 字符即完成点击 |
| 精准点击困难 | 小按钮、密集菜单难以命中 | Grid 网格细分：Q/W/E 三层即可精确定位 |
| 重复操作无自动化 | 相同序列每天手动重复 | 修饰键系统：Shift→右键 / Option→拖拽 / Cmd→锁定 |
| Canvas/Electron 不可访问 | Accessibility API 检测不到 | Hint+Grid 混合：自动回退，无感切换 |
为什么做这个方向
我做的是一个明确的取舍判断：
- 不是鼠标替代器：不追求「能用键盘完成 100% 鼠标操作」这种极限目标，而是覆盖 80% 高频场景
- 不是小众极客玩具：不只是 Vim 用户的工具，面向所有键盘重度用户
- 是统一键盘交互平台：Hint + Grid + Scroll + Search 一套体验，相互组合形成闭环
核心竞争力：Hint + Grid 混合模式是当前竞品没有的差异化能力——在任何场景下（包括 Canvas、Electron、视频播放器）都保证「可点击」，这是 Vimac/Shortcat/Homerow 都做不到的。
三、体验地址
macOS app
- MacimApp.zip 下载(3.4 MB)
完成授权后点击状态栏图标菜单 “Entrer Hintmode”
再按标签提示字符串点击键盘，执行
html 体验方式
-
下载
Macim_Creative_Showcase.html.zip (11.9 KB)
-
解压后用现代浏览器（Chrome 90+ / Safari 14+ / Firefox 88+）打开
Macim_Creative_Showcase.html (48.1 KB) -
滚动到「Core Features」区块，点击 Hint / Grid / Scroll tab 体验三种核心交互
可体验的交互
html 文件中包含 3 个真实可交互 Demo，完整复刻 Macim 核心交互概念：
| Demo | tab | 可体验按键 |
|---|---|---|
| HintMode | Hint | 任意 a-z 字母键（前缀匹配标签高亮，完全匹配触发点击反馈）；Esc 重置；Backspace 退格 |
| GridMode | Grid | Q/W/E/A/S/D/Z/X/C 切换格子高亮；Space/Enter 触发当前格子确认反馈 |
| ScrollMode | Scroll | j/k 上下滚动一行；d/u 半页滚动；连按两次 g（gg）跳顶；G（Shift+g）跳底 |
操作要点
- 切换 tab 时 Demo 区域自动聚焦并显示绿色外边框（视觉提示已就绪）
- 无需点击 Demo 区域即可直接键盘输入
- HintMode：试试在键盘上输入
s（多个s开头的标签会高亮），再输入a组成sa触发「文件」元素点击反馈 - GridMode：初始 S 中心格高亮，按
Q切换到左上角，按Space触发确认反馈 - ScrollMode：内容区有 18 行文本，按
j多次向下滚动，按gg回到顶部
浏览器兼容性
支持 Chrome 90+ / Safari 14+ / Firefox 88+ 现代浏览器。使用标准 Web API（document.addEventListener、element.scrollTo、IntersectionObserver、classList），字体通过 Google Fonts CDN 引用，离线时降级为系统等宽字体。
四、TRAE 实践过程
本项目从需求拷问到架构设计、从功能实现到工程化，全部基于 TRAE IDE 完成。以下是关键步骤与对应的 TRAE 能力应用。
4.1 项目架构设计
Macim 采用严格的三层架构，所有架构决策都通过 TRAE 的设计规范驱动开发流程落地：
通过 TRAE 的 dd-feature-development-workflow skill，每个新功能都先写设计规范、再拆计划、按子计划 TDD 实现，避免「先写代码再补文档」的漂移。
4.2 核心功能实现：HintMode 状态机
HintMode 是 Macim 的主线功能，核心是一个有限状态机：
Inactive → Activating → Active → Matching → Confirmed → Inactive
↑ ↓
└── Esc ──────┘
关键 Session（如下方 Session ID 列表所示）覆盖了：
- HintMode 状态机骨架：使用
@MainActor边界管理 UI 状态更新，避免并发竞态 - 多区域扫描：通过 Accessibility API 遍历系统级 AXUIElement 树，按区域分组生成标签
- 标签生成算法：基于元素数量动态生成 2-3 字符标签（如
sa/sd/sf），保证前缀唯一性 - 双通道匹配：标签前缀匹配 + 元素文本模糊搜索，让用户既能输入标签也能输入元素名
通过 TRAE 的对话式 AI 辅助，复杂的状态机逻辑、AX 查询边界条件、标签冲突处理都得到了快速实现与验证。
4.3 关键 Session ID
以下 Session ID 在 TRAE IDE 中产生，用于证明本作品由 TRAE 完成。按时间顺序排列：
| # | Session ID | 日期 | 主题 |
|---|---|---|---|
| 1 | 6a14647624c8edfc1ad9271d |
2026-06-16 | DependencyContainer 编译错误修复 |
| 2 | 6a14e97b1710dcdbcc9b948c |
2026-06-16 | 创建 Issue #77 — Xcode 文件 Tab 右键菜单不退出 HintMode 的 bug 报告 |
| 3 | 6a35b633ad2262694d491aa8 |
2026-06-20 | 跨屏焦点边框修复（codex/fix-cross-screen-focus-border 分支变基合并到 develop） |
| 4 | 6a37ff9fc9a431ccca0cb664 |
2026-06-21 | F12a~F12f 编号调整，推荐 F1.12.1~F1.12.6 数字子编号方案 |
| 5 | 6a45c0f204050f6b0ba6dd3e |
2026-07-02 | swiftlint 版本切换 |
可直接复制 Session ID 到 TRAE 中查看完整对话历史。
报名帖链接
- TRAE AI 创造力大赛报名帖： 【学习工作赛道】Macim：全键盘控制 macOS 的效率应用