hmharness解决终端AI交互痛点，移除全局鼠标捕获，恢复原生复制功能

在 AI 编程助手日益普及的当下，一个看似微小却高频发生的体验断点正困扰着开发者：当模型生成一段命令、路径或代码片段后，用户试图用鼠标划选并复制——却发现终端光标被 TUI（文本用户界面）劫持，无法触发原生选择器。这一问题并非源于模型能力不足，而是终端交互层的设计取舍所致。近期，开源项目 hmharness 通过一项关键调整，系统性解决了该问题。

hmharness 是一个面向 HarmonyOS/OpenHarmony 的智能体开发框架，核心目标是构建“生成-验证-执行”闭环：不仅让 AI 生成代码，更要求其在本地环境完成工程创建、构建、安装、启动与结果验证。它并非 DevEco Studio 的替代品，而是在开发智能体与鸿蒙工具链之间增设的验证层，确保 AI 行为可追溯、可回滚、受约束。

在众多交互细节中，复制粘贴问题尤为突出。传统 TUI 应用若启用 1000h（鼠标按钮事件）、1002h（鼠标移动+按钮）或 1006h（SGR 格式坐标报告）等终端序列，会开启全局鼠标捕获。此时，所有鼠标事件（包括拖拽划选）优先由应用处理，终端自身的原生选择机制被绕过。对开发者而言，这意味着日常高频操作——如复制报错栈、路径或命令行片段——必须退出当前界面或手动切换模式才能完成，效率严重受损。

为解决此问题，hmharness 在其主入口 public main 中明确禁止上述鼠标报告序列的初始化。具体而言，启动时不再发送 1000h、1002h 或 1006h 控制码，从而确保终端原生选择与复制功能在任何时刻均可使用。这一决策并非功能退化，而是边界重划：将精确选择权留给用户与终端，将导航类交互（如列表滚动）交由应用处理。

随之而来的问题是：去除全局鼠标捕获后，滚轮如何响应？hmharness 采用 ?1007（alternate scroll）模式。该模式下，终端在备用屏幕缓冲区中将滚轮事件自动转换为 ESC [A（上）与 ESC [B（下）方向键序列。TUI 的选择器（picker）仅需监听方向键即可实现选项移动，无需感知鼠标坐标。实测表明，在 /model picker 等界面中，滚轮下滚等效于按 ↓ 键，上滚等效于 ↑ 键，行为一致且无延迟。

在交互逻辑上，picker 彻底回归键盘优先原则：方向键移动选项，Enter 确认，Esc 退出。这既符合终端用户的肌肉记忆，也避免了因依赖鼠标坐标而引入的不确定性。值得注意的是，即便应用未主动开启鼠标报告，某些终端环境仍可能因历史状态残留或异常输入产生杂散 SGR 报文（如 ESC [M）。若此类字节被误读为普通输入，可能导致命令草稿污染或意外触发动作。hmharness 对此采取“防御性吞掉”策略——直接丢弃无法识别的 SGR 字节流，确保输入流纯净。

上述改进已在提交 c6fdd73422ef8cb05d41412ed448e7d4e8f5a226 中固化，并通过 CI 测试验证：共运行 1068 项测试，1067 项通过，0 失败，1 项跳过。本地复现测试覆盖核心场景：?1007 滚轮转方向键、全局鼠标捕获永久移除、picker 键盘驱动、杂散 SGR 报文过滤，全部通过。

需要强调的是，该方案并非临时折衷。早期版本曾尝试“临时开启鼠标跟踪”以支持点击选择，但最终被放弃。当前设计以 public main 主干为准，拒绝中间态妥协，坚持“原生选择始终可用”的原则。这也反映出 hmharness 的底层哲学：AI 智能体不应以牺牲终端基本交互为代价换取界面精致度；工具链的可靠性，优先于视觉交互的完整性。

从行业视角看，此类问题具有普遍性。许多基于 TUI 的 AI 编程工具（如 Cursor、CodeLlama CLI、GitHub Copilot Terminal 插件等）均面临类似权衡。终端作为开发者最基础的操作界面，其原生能力（划选、复制、滚屏）已被数十年实践验证为高效范式。任何上层应用若想覆盖这些行为，必须提供同等甚至更高的操作效率作为补偿——而目前多数方案并未做到。

hmharness 的做法提供了一种可行路径：通过精细控制终端序列（如仅启用 ?1007 而非 1002h），在保留必要导航能力的同时，将高频原子操作交还给终端。这种“最小干预”原则，对构建真正可落地的 AI 开发工具链具有参考价值。

目前，hmharness 的 npm 包 @hmharness/cli@0.23.50 已同步该实现，GitHub 最新发布版本亦包含此项改进。对于正在构建终端侧 AI 助手的团队而言，其源码与测试用例构成了一份可复用的交互规范样本：不是所有“现代化”都需要鼠标点击；有时，退回键盘与原生终端，反而是更先进的选择。