# dsh-plugin-eyes — ojos, manos y OCR local para DeepSeek Harness en Windows

Plugin MCP local que le da a DSH visión, control y lectura del escritorio de
Windows: 19 herramientas `mcp__eyes__*` registradas con la fila oficial
`@deepseek-ai/dsh-mcp-client`. Sin servidor externo, sin proveedor de visión, sin
dependencias nativas de npm y **sin red para el OCR**.

[English](README.en.md) · [Cómo funciona](docs/COMO-FUNCIONA.md) · MIT

## Instalación

**Recomendada (gestor de plugins / página Plugins de DSH):**

```
dsh plugin --profile <perfil> add dsh-plugin-eyes
# o directo desde GitHub:
dsh plugin --profile <perfil> add github:thegabopacheco-sudo/dsh-plugin-eyes
```

En la app de escritorio el perfil lo administra la aplicación: instalalo desde
**Settings → Plugins** (o pedile al agente que use el plugin manager). El paquete
trae un `postinstall` que copia el runtime a `<DSH_HOME>\plugins\eyes`; pnpm puede
pedirte **permitir el build script** — aceptá (*Permitir estos scripts y
reintentar*). No instala nada global, no toca el registro, no crea servicios.

**Manual (desarrollo/offline):**

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall
```

Requisitos: Windows 10 19041+/11, PowerShell 5.1 (incluido), Node ≥20 (lo aporta
DSH), .NET Framework 4.x (incluido) para `eyes-capture.exe`. El OCR usa los
idiomas OCR de Windows instalados.

## Herramientas (19)

### Ojos
| Tool | Qué hace |
|---|---|
| `screenshot` | Captura pantalla (todos los monitores), monitor, ventana o región y devuelve la imagen **dentro del tool result**. Opciones: `grid`, `showCursor`, `marks` (Set-of-Marks), `clipboard`, `focus`. |
| `list_windows` / `list_screens` | Ventanas visibles / monitores y escritorio virtual. |
| `ocr` | **OCR local** (Windows.Media.Ocr, sin red): líneas + palabras con coordenadas absolutas; `query` filtra y `boxes:true` devuelve cajas. Funciona en Chrome/Electron. |
| `click_text` | OCR + click: encuentra texto visible y lo clickea (`dryRun:true` sólo reporta coordenadas). |

### Manos
| Tool | Qué hace |
|---|---|
| `click` | Click izquierdo/derecho/medio en píxeles físicos del escritorio virtual. |
| `move_mouse` / `scroll` | Mueve el cursor / gira la rueda (positivo = arriba). |
| `type` / `press` | Texto unicode / combinación de teclas. Con `window` abortan si la ventana ya no existe. |
| `drag` | Press en (x,y), mover a (toX,toY), soltar (drag & drop, sliders). |
| `window_action` | `focus`, `minimize`, `maximize`, `restore` o `close`. |
| `clipboard_get` / `clipboard_set` | Lee / escribe el portapapeles. |
| `batch` | Hasta 30 acciones en una llamada; corta al primer error; `verifyFinal` devuelve captura final. |

### UI Automation
| Tool | Qué hace |
|---|---|
| `ui_tree` | Árbol acotado: nombre, `AutomationId`, tipo, bounds, acciones. |
| `ui_text` | Texto vía `ValuePattern`/`TextPattern`. |
| `ui_click` / `ui_set_value` | Actúa por nombre o `AutomationId`. **Rechaza campos de contraseña.** |

### Act-and-verify
`click`, `scroll`, `type`, `press`, `ui_click`, `ui_set_value` y `click_text`
aceptan `verify:true` y devuelven captura posterior; `batch` devuelve la final.

## Ejemplos de uso

- «mirá mi pantalla y decime qué ves»
- «leé lo que dice esta ventana de Chrome» → `ocr`
- «buscá el botón Guardar y tocá» → `click_text`
- «completá el formulario: escribí X, tab, Y y enviá» → `batch`
- «abrí el menú Archivo de Notepad y decime las opciones» → `ui_tree` + `ui_click`
- «copiá esta captura y pegala en el chat» → `screenshot clipboard:true` + `press ctrl+v`

Apps nativas → UI Automation; web/Electron → `ocr` + `click_text` o screenshot con
`grid`/`marks`.

## Seguridad

- `DSH_EYES_MODE=read-only` desactiva todas las acciones de input.
- Cada acción mutante se registra en `<DSH_HOME>\cache\eyes\audit.jsonl`.
- Campos de contraseña rechazados; Set-of-Marks no los numera.
- `type`/`press`/`click`/`drag` con `window` abortan si la ventana desapareció.
- Capturas locales (`~/.dsh/cache/eyes`, máx. 40 + archivos OCR).

Límites: `SendInput` no atraviesa UIPI/secure desktop (UAC/bloqueo);
Chrome/Electron exponen poco UI Automation; `PrintWindow` suele ser rechazado por
Chromium (se captura el área visible); ventanas minimizadas no se capturan.

## Arquitectura

```
server.mjs + tools-extra.mjs ─► MCP stdio (fila de @deepseek-ai/dsh-mcp-client)
        ├─ eyes-capture.exe  ← C#: GDI, PrintWindow+DWM, DPI-aware, multi-monitor,
        │                       SendInput, portapapeles, UI Automation, marks,
        │                       drag y acciones de ventana
        └─ ocr.ps1           ← Windows.Media.Ocr (WinRT) sobre un PNG ya capturado
```

- El servidor usa `@modelcontextprotocol/server@2.2.0` (protocolo 2026-07-28).
- El capturador es `.exe` porque un `.ps1` con `Add-Type` + `CopyFromScreen` fue
  bloqueado por AMSI/Defender como contenido malicioso; el OCR corre en otro
  script PowerShell **sin código de captura** y escribe JSON UTF-8 a un archivo.
- `cordis.patch.yml` inserta una fila de `@deepseek-ai/dsh-mcp-client` sin rutas
  de máquina: `command` = `process.execPath`, servidor en `<DSH_HOME>/plugins/eyes`.

## Comparación (2026-11-10)

| | eyes | appshot | vision-toolkit | codex-style |
|---|---|---|---|---|
| Windows | ✅ | ✅ | ✅ | ✅ |
| Imagen dentro del tool result | ✅ | ✅ | ❌ | parcial |
| Manos (click/teclado/drag/ventana) | ✅ | ❌ | ❌ | ✅ |
| UI Automation | ✅ | ❌ | ❌ | ✅ |
| OCR local con cajas + click_text | ✅ | ❌ | ✅ | ✅ |
| Set-of-Marks + verify + batch | ✅ | ❌ | ❌ | ✅ (batch) |
| read-only + audit | ✅ | ❌ | ❌ | ✅ (4 modos) |
| Settings card / hotkey | ❌ roadmap | ✅ | ✅ | ❌ |
| Peso | **~47 KB exe + bundle 1,2 MB** | 42,2 MB | 10,1 MB | 9,1 MB |

## Desarrollo

```powershell
npm install
npm run build:bundle     # dist/server.mjs (esbuild)
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Force   # eyes-capture.exe (csc.exe)
cd test; npm install; node connect-test.mjs; node connect-test-extra.mjs
```

## Licencia

MIT © thegabopacheco-sudo