dsh-gesture-mouse

macOS 摄像头手势鼠标的 DeepSeek Harness 插件。DSH 插件是安装与控制入口， 随包附带的 Swift Helper 负责实时视觉识别和系统鼠标事件。

> 社区项目，非 DeepSeek 官方组件。当前版本是面向真机标定的 V0 基线。

定位

这不是把每一帧摄像头画面交给大模型。实时路径始终在 Mac 本机：

Camera → AVFoundation → Apple Vision hand joints → state machine
       → One Euro filter → CoreGraphics mouse events

named special gesture → structured trigger only → DSH plugin router
                       → deterministic action or opt-in DeepSeek plan

• 移动、点击、双击、拖拽、滚动、离合与紧急暂停不经过 LLM。
• IPC 只传状态、统计和 gestureId/confidence/timestamp，不传图像或关节点。
• 特殊手势默认禁用；DeepSeek 路由在 V0 只生成安全计划，不自动启动模型会话。

能力

• 食指指向控制相对光标。
• 拇指与食指捏合完成点击或按住拖拽。
• 食指与中指控制滚动。
• 张掌离合；保持张掌触发本地 panic。
• DSH 工具：gesture_status、gesture_start、gesture_stop、gesture_test_trigger。
• 每个特殊手势强制冷却、去重和每分钟上限。
• DSH dispose 时通过鉴权 IPC 退出 Helper，并在超时时仅终止已确认的 Helper PID。

要求与权限

• macOS 13 或更高版本。
• DeepSeek Harness / dsh CLI。
• Node.js 20 或更高版本。
• Xcode / Swift 6（从源码构建时需要）。
• Camera：读取摄像头帧，仅在内存中处理。
• Accessibility / PostEvent：通过 CoreGraphics 合成鼠标事件。

不需要 Screen Recording。默认不监听键盘，因此也不请求 Input Monitoring。

构建与验证

npm install
npm run build
npm run typecheck
npm test
npm run verify

npm run verify 会重新构建 Swift Helper、检查签名与 Info.plist、运行 TypeScript 类型检查、单元测试、doctor 和敏感信息扫描。

安装

npm pack
dsh plugin --profile web add ./dsh-gesture-mouse-0.1.0.tgz

重启 DeepSeek Harness。默认 autoStart: false，首次请显式调用 gesture_start，然后在 macOS 设置中批准 Camera 与 Accessibility 权限。

配置

DSH bundle 默认配置位于 [cordis.patch.yml](cordis.patch.yml)。完整示例见 [examples/cordis.patch.yml](examples/cordis.patch.yml)。

关键配置：

• autoStart：默认 false，禁止安装后自动打开摄像头。
• sensitivity：相对光标灵敏度。
• cameraFPS：目标采集帧率，默认 30。
• minimumConfidence：Vision 关节点最低置信度。
• routes：命名特殊手势；每条都必须显式 enabled: true。

安全下限不可通过配置削弱：冷却至少 10 秒、去重至少 3 秒、每分钟最多 3 次。

使用

1. 调用 gesture_start，根据系统提示授权。 2. 调用 gesture_status 检查 cameraAuthorized、postEventAuthorized、FPS 与推理延迟。 3. 伸出食指稳定约 200ms 后移动光标；张掌冻结。 4. 用 gesture_test_trigger 在不打开摄像头的情况下测试特殊手势路由。 5. 调用 gesture_stop 释放摄像头。

卸载与数据删除

dsh plugin --profile web remove dsh-gesture-mouse

退出 DSH 或卸载插件会停止 Helper 和摄像头。运行时 socket/token 位于 ~/.dsh/state/dsh-gesture-mouse/，正常退出会删除；异常残留可在 Helper 停止后 手动删除该目录。macOS TCC 权限记录由系统管理，需要用户在“系统设置 → 隐私与安全性” 中撤销 Camera/Accessibility 权限。

限制

• V0 参数尚需真人真机标定；不要把它作为唯一输入设备。
• 复杂 DeepSeek 路由尚未执行 session.prompt，当前只返回计划。
• 暗光、遮挡、摄像头角度和手型会影响 Vision 置信度。
• 当前只处理一只手；不支持多手协作。
• V1 生命周期绑定 DSH；脱离 DSH 独立运行属于后续范围。

架构与非目标

• DSH 插件：Helper 生命周期、配置、状态、诊断、IPC 鉴权和特殊手势路由。
• Swift Helper：摄像头、Vision、状态机、滤波、鼠标事件和本地 fail-safe。
• 非目标：上传视频、保存关键点、逐帧调用 DeepSeek、读取屏幕、通用桌面自动化。

详细状态机、延迟预算和阶段计划见 [docs/gesture-design.md](docs/gesture-design.md)。

社区与许可证

仓库使用 dsh-plugin topic 参与 DSH 社区发现。MIT License。