dsh-gesture-mouse

Readme

# dsh-gesture-mouse

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

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

## 定位

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

```text
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。

## 构建与验证

```bash
npm install
npm run build
npm run typecheck
npm test
npm run verify
```

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

## 安装

```bash
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` 释放摄像头。

## 卸载与数据删除

```bash
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。