# dsh-plugin-ui-bridge — puente de interfaz Windows para DeepSeek Harness

Plugin MCP local que le da al agente acceso estructurado a **ventanas y apps de
Windows**: listar ventanas, capturarlas, inspeccionar la interfaz por **UI
Automation**, hacer clic y escribir por identidad de elemento, controlar ventanas
y lanzar apps de una lista blanca (Discord, navegador, notepad, launcher…).

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

## Herramientas (11)

| Tool | Qué hace |
|---|---|
| `mcp__ui_bridge__windows` | Lista ventanas visibles con título, PID y rectángulo. |
| `mcp__ui_bridge__window_capture` | Captura una ventana (opcionalmente la trae al frente) y devuelve la imagen. |
| `mcp__ui_bridge__window_action` | Enfoca, minimiza, maximiza, restaura o cierra una ventana. |
| `mcp__ui_bridge__ui_tree` | Árbol de UI Automation acotado: nombre, automationId, tipo, bounds y acciones. |
| `mcp__ui_bridge__ui_text` | Lee el texto de una ventana (los campos de contraseña se omiten). |
| `mcp__ui_bridge__ui_click` | Clic por nombre o `automationId` (invoke/toggle/select o clic al centro). |
| `mcp__ui_bridge__ui_set_value` | Escribe en un elemento por nombre o `automationId`. |
| `mcp__ui_bridge__type` | Escribe texto unicode en la ventana/control enfocado. |
| `mcp__ui_bridge__press` | Presiona una combinación (`ctrl+s`, `alt+tab`, `enter`…). |
| `mcp__ui_bridge__app_launch` | Lanza apps de la lista blanca (notepad, chrome, edge, discord, explorer…). |
| `mcp__ui_bridge__status` | Estado del helper, modo, lista blanca y auditoría. |

## Instalación

Desde **DSH → Settings → Plugins** instala
`github:thegabopacheco-sudo/dsh-plugin-ui-bridge` y permite el script de
instalación cuando DSH lo pida.

Por CLI (perfiles que no administra la app):

```
dsh plugin --profile <perfil> add github:thegabopacheco-sudo/dsh-plugin-ui-bridge
```

El `postinstall` copia el servidor, el helper nativo (`windows-bridge.exe`) y el
`package.json` a `<DSH_HOME>\plugins\ui-bridge`.

Requisitos: Windows 10/11 y Node ≥ 20 (lo aporta el harness). El helper nativo se
compila con el `csc.exe` de .NET Framework que ya trae Windows (el `.exe`
precompilado viene incluido).

## Uso típico

1. «Lista las ventanas y dime si Discord está abierto.»
2. «Enfoca Discord, ábreme el árbol de la barra lateral y dime los canales.»
3. «Haz clic en el canal `#anuncios`.»
4. «Captura la ventana de Notepad y describe lo que se ve.»
5. «Abre Notepad con este archivo y escribe una nota de prueba.»

## Seguridad

- **Lectura por defecto**; las acciones solo se ejecutan cuando el usuario las pide.
- **Lista blanca de ventanas** opcional: `DSH_UIBRIDGE_ALLOWED_WINDOWS=discord,notepad`.
- **Campos de contraseña rechazados** por el motor UIA y omitidos al leer texto.
- **Nunca a ciegas**: `type`/`press` con ventana abortan si la ventana no existe.
- **Auditoría** de acciones en `<DSH_HOME>\cache\ui-bridge\audit.jsonl`.
- **Rate limit** de 60 acciones por minuto.
- **Read-only**: `DSH_UIBRIDGE_MODE=read-only` desactiva todas las acciones.
- Apps: solo las de la lista blanca (se puede extender con `DSH_UIBRIDGE_APPS`).

## Variables de entorno

| Variable | Uso |
|---|---|
| `DSH_UIBRIDGE_MODE` | `read-only` desactiva acciones. |
| `DSH_UIBRIDGE_ALLOWED_WINDOWS` | Lista blanca de títulos (substrings separados por comas). |
| `DSH_UIBRIDGE_APPS` | JSON `{ "mi-app": "C:\\ruta\\app.exe" }` para apps extra. |
| `DSH_UIBRIDGE_SKIP_POSTINSTALL` | `1` omite el despliegue del postinstall. |

## Solución de problemas

- **“Install scripts need your permission”**: aprueba el `postinstall`. Si el
  cartel se repite, revisa `<perfil>\pnpm-workspace.yaml`: `allowBuilds` debe
  valer `true`, no el placeholder `set this to true or false`.
- **No aparecen las tools**: verifica `<DSH_HOME>\plugins\ui-bridge\server.mjs` y
  `windows-bridge.exe`; revisa la fila `mcp-ui-bridge` y reinicia DSH.
- **UI Automation viene vacía**: algunas apps UWP exponen el árbol completo solo
  cuando la ventana está activa; usa `window_action focus` primero.
- **App no permitida**: agrega la ruta con `DSH_UIBRIDGE_APPS`.

## Desarrollo

```powershell
npm install
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Force   # windows-bridge.exe
npm run build:bundle                                           # dist/server.mjs
cd test; npm install; node connect-test.mjs
```

## Licencia

MIT © thegabopacheco-sudo