dsh-click 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# 🖱️ dsh-click
+
+**Cross-platform native desktop control for DeepSeek Harness — Windows first.**
+
+*Look at the screen, then act — every click gated, every action audited.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-click/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-click/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-click?label=version)](https://github.com/PerryLink/dsh-click/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-click)](https://www.npmjs.com/package/dsh-click)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-click)](https://www.npmjs.com/package/dsh-click)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## Compatibility
+
+| Surface | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` (compat declared for `0.1.0-rc.5`–`0.1.0-rc.6`) |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Platforms | **Windows first** (UIAutomation + Win32 input, via a bundled PowerShell helper); macOS/Linux backends are reserved and fail closed with a clear reason |
+| Model | Text-only models fully supported (`screen_read` returns structured text); vision models additionally get `screen_shot` images |
+
+## What you get
+
+`dsh-click` gives the harness a complete observe → act loop over native desktop applications:
+
+- **`screen_shot`** — screenshot of a window (or the primary screen), downscaled to a configurable bound. With a vision-capable model the result carries the image; otherwise a text description keeps text-only models working.
+- **`screen_read`** — the structured observation: the window's accessibility tree (element ids, types, names, rectangles, supported patterns) plus pixel-location hints with colors — plain text, no image model required.
+- **`click` / `type` / `scroll` / `key`** — window-scoped actions addressed by element id or coordinates. Delivery prefers UIA invoke, falls back to posted window messages — and **never steals foreground focus**.
+- **`app_list` / `app_launch`** — enumerate running applications and their windows; launch one by name or path.
+
+Every mutating action crosses one safety boundary:
+
+1. **Freshness** — the action must cite a `basedOn` observation; the window is re-captured right before acting and the action is refused if the screen changed (pixel-hash check + max-age bound).
+2. **Approval** — `ctx.approval` gates every action by default; window-title/executable regexes can allowlist specific windows (still audited).
+3. **Process identity** — the owning process's pid and executable path are verified before **and** after the act; a change refuses the outcome loudly.
+4. **Audit** — observations and actions land in the session log as `dsh-click/observed` / `dsh-click/action` events (sanitized, log-only).
+
+```text
+model                           harness
+  │ screen_read ──▶ observationId (+ elements, pixels)         ← structured text
+  │ click {basedOn, target} ──▶ freshness check ──▶ approval ──▶ helper (UIA)
+  │                             pixel hash changed? ── refuse + re-observe
+  │                             pid/exe changed after act? ── PROCESS_CHANGED
+  │ ◀── canonical JSON + audit events (dsh-click/action)
+```
+
+## Quick start
+
+```sh
+# 1. install the bundle into your profile
+dsh plugin --profile web add "github:PerryLink/dsh-click#main"
+
+# or from npm (published releases)
+dsh plugin --profile web add dsh-click
+
+# 2. restart and verify the row
+dsh --profile web --dump-config | grep -A2 'id: dsh-click'
+```
+
+Then ask the agent to look at a window and act — the approval prompt appears for every mutating action:
+
+```
+> Open Notepad, type "hello", then read back what is on screen.
+```
+
+## Install & uninstall
+
+- **git channel** (latest `main`): `dsh plugin --profile web add "github:PerryLink/dsh-click#main"` — the `prepare` script builds with production dependencies only.
+- **npm channel** (published releases): `dsh plugin --profile web add dsh-click`.
+- **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-click-<version>.tgz`.
+- **uninstall**: `dsh plugin --profile web remove dsh-click` (or remove the row from the profile patch).
+
+## Configuration
+
+All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. `cordis.patch.yml` documents each key inline.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `requireApproval` | `true` | Gate every mutating action behind approval; observers never ask |
+| `autoApproveWindows` | `[]` | Window-title/executable regexes that skip the approval ask (still freshness-checked and audited) |
+| `focusFallback` | `never` | Whether an action may bring the target window to the foreground as a last resort (`never` / `allow`) |
+| `imageMode` | `auto` | `screen_shot` rendering: `auto` (image when the model accepts images, text otherwise) or `text` |
+| `helperTimeoutMs` | `30000` | Per-helper-call timeout in ms (1..300000) |
+| `maxHelperOutputBytes` | `25165824` | Cap on one helper response in bytes (1024..67108864) |
+| `maxScreenshotSide` | `2560` | Longest screenshot side in pixels (320..7680); larger captures are downscaled |
+| `staleCheckPixels` | `true` | Compare a fresh pixel hash before every action and refuse on change |
+| `maxObservationAgeMs` | `30000` | Maximum age in ms of an observation an action may cite (1000..600000) |
+| `maxCachedObservations` | `8` | LRU cap on cached observations (1..64) |
+| `maxElements` | `500` | Cap on accessibility elements per `screen_read` (1..2000) |
+| `maxTreeDepth` | `32` | Maximum accessibility tree-walk depth (1..64) |
+| `maxTextLength` | `200` | Truncation length for sanitized model-visible strings (16..10000) |
+| `rollbackEnabled` | `true` | Back up and restore control text when `type` fails |
+
+Example override in your profile patch:
+
+```yaml
+- insert:
+    - id: dsh-click
+      name: dsh-click
+      config:
+        requireApproval: true
+        autoApproveWindows: ['^Notepad']
+        focusFallback: never
+```
+
+## Tools & surfaces
+
+| Tool | Read-only | Needs approval | Notes |
+|---|---|---|---|
+| `screen_shot` | ✅ | — | Returns an `observationId` later actions cite in `basedOn`; image attachment when the model accepts images |
+| `screen_read` | ✅ | — | Accessibility tree + pixel hints; element ids are what actions address |
+| `click` | | ✅ | Exactly one of `elementId` or `(x, y)`; UIA invoke preferred, posted messages fallback |
+| `type` | | ✅ | Value-pattern elements only; backs up and restores control text on failure |
+| `scroll` | | ✅ | Element (scroll pattern) or window (posted wheel) |
+| `key` | | ✅ | Posted key combinations (`"Ctrl+S"`); apps that ignore posted input refuse loudly |
+| `app_list` | ✅ | — | Running applications and their visible windows |
+| `app_launch` | | ✅ | By name or executable path, with optional arguments |
+
+## Permissions & data
+
+- **Permissions**: mutating actions cross the official `ctx.approval` seam — the plugin never re-implements or bypasses it. The allowlist only ever *skips the ask for specific windows*; it cannot disable the freshness or process-identity checks.
+- **Data**: the plugin stores nothing on disk except the screenshots the attachment store keeps (content-addressed, under the harness's own attachment policy). Observations are cached in memory (LRU, bounded). No network requests, no credential storage.
+- **Session log**: `dsh-click/observed` and `dsh-click/action` are log-only audit events carrying sanitized window/process facts — titles, paths, and free text are redacted and length-capped before they are written or shown.
+
+## Security boundaries
+
+- **Observe before act, every time.** Actions must cite a fresh observation; a changed screen (pixel hash) or an expired observation is refused with a model-readable reason demanding re-observation.
+- **Approval is the default.** `requireApproval: true` unless you explicitly opt specific windows in; every action — allowed or not — is audit-logged.
+- **No foreground stealing.** The helper never brings a target window to the foreground (`focusFallback: 'never'` by default); input is delivered through UIA or posted messages so background windows are not disturbed.
+- **Process identity is re-verified** immediately before and after each action; a mid-act process swap fails the outcome (`PROCESS_CHANGED`).
+- **Sanitized output.** Control characters are stripped, tabs collapse, credential-shaped values (keys, tokens, JWTs, bearer headers) are redacted before anything reaches the model or the log.
+- **Fail closed.** Unsupported platforms, a missing subprocess service, or an unavailable helper refuse every call loudly — profiles keep booting everywhere.
+
+## Known limitations
+
+- **Windows first.** macOS and Linux backends are reserved; on those platforms every call fails closed with a clear reason.
+- **Text-only fidelity.** `screen_read` depends on the application exposing UIAutomation; apps without an accessible tree yield pixel hints only. Coordinate clicks remain available.
+- **Posted-input apps.** Some applications ignore posted window messages (games, some Electron surfaces); `key` reports this honestly instead of pretending success.
+- **Session audit on newer harness builds.** The audit events are appended with the two-argument `Session.append` form (the pinned `0.1.0-rc.6` peers have no append-envelope option); on post-rc.6 builds the events are required-on-read, which is fine while this plugin is installed because it declares those event types.
+
+## Development
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc: src + tests against the local harness checkout
+pnpm run typecheck:ci  # tsc against the published 0.1.0-rc.6 types (no paths)
+pnpm test           # vitest: 56 tests, 8 suites (helper smoke runs on Windows)
+pnpm run build      # tsdown bundle + tsc declarations (lib/)
+pnpm run verify:self-contained  # dependency specs resolve from the registry
+pnpm run verify:artifacts       # built ESM face + native helper present
+pnpm pack           # the published tarball
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `computer-use`, `windows-automation`, `uiautomation`, `desktop-control`, `screen-reader`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: tool surface, action safety boundary, Windows native helper, sanitizers, and the five-language docs.
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-click contributors

package/README.pt.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# 🖱️ dsh-click
+
+**Controle nativo de desktop multiplataforma para o DeepSeek Harness — Windows primeiro.**
+
+*Olhe para a tela e então aja — cada clique autorizado, cada ação auditada.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-click/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-click/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-click?label=version)](https://github.com/PerryLink/dsh-click/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-click)](https://www.npmjs.com/package/dsh-click)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-click)](https://www.npmjs.com/package/dsh-click)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## Compatibilidade
+
+| Superfície | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` (compatibilidade declarada para `0.1.0-rc.5`–`0.1.0-rc.6`) |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Plataformas | **Windows primeiro** (UIAutomation + entrada Win32, via um helper PowerShell embutido); os backends macOS/Linux estão reservados e falham fechado com um motivo claro |
+| Modelo | Modelos somente texto totalmente suportados (`screen_read` retorna texto estruturado); modelos com visão recebem também as imagens do `screen_shot` |
+
+## O que você ganha
+
+O `dsh-click` dá ao harness um ciclo completo de observar → agir sobre aplicativos de desktop nativos:
+
+- **`screen_shot`** — captura de uma janela (ou da tela principal), reduzida a um limite configurável. Com um modelo com visão o resultado traz a imagem; caso contrário, uma descrição em texto mantém os modelos somente texto funcionando.
+- **`screen_read`** — a observação estruturada: a árvore de acessibilidade da janela (ids de elementos, tipos, nomes, retângulos, padrões suportados) mais dicas de pixels com cores — texto puro, sem exigir modelo de imagem.
+- **`click` / `type` / `scroll` / `key`** — ações limitadas à janela, endereçadas por id de elemento ou coordenadas. A entrega prefere UIA invoke e recorre a mensagens de janela postadas — e **nunca rouba o foco em primeiro plano**.
+- **`app_list` / `app_launch`** — enumera os aplicativos em execução e suas janelas; inicia um por nome ou caminho.
+
+Toda ação mutante cruza uma mesma fronteira de segurança:
+
+1. **Atualidade** — a ação deve citar uma observação `basedOn`; a janela é recapturada logo antes de agir e a ação é recusada se a tela mudou (hash de pixels + limite de idade).
+2. **Aprovação** — `ctx.approval` protege cada ação por padrão; regex de título/executável podem liberar janelas específicas (ainda auditadas).
+3. **Identidade do processo** — o pid e o caminho do executável dono são verificados antes **e** depois do ato; uma mudança recusa o resultado em voz alta.
+4. **Auditoria** — observações e ações entram no registro de sessão como eventos `dsh-click/observed` / `dsh-click/action` (sanitizados, somente registro).
+
+```text
+modelo                          harness
+  │ screen_read ──▶ observationId (+ elementos, pixels)        ← texto estruturado
+  │ click {basedOn, target} ──▶ verificação de atualidade ──▶ aprovação ──▶ helper (UIA)
+  │                             hash de pixels mudou? ── recusar + reobservar
+  │                             pid/exe mudou após o ato? ── PROCESS_CHANGED
+  │ ◀── JSON canônico + eventos de auditoria (dsh-click/action)
+```
+
+## Início rápido
+
+```sh
+# 1. instale o bundle no seu perfil
+dsh plugin --profile web add "github:PerryLink/dsh-click#main"
+
+# ou pelo npm (versões publicadas)
+dsh plugin --profile web add dsh-click
+
+# 2. reinicie e verifique a linha
+dsh --profile web --dump-config | grep -A2 'id: dsh-click'
+```
+
+Depois peça ao agente para olhar uma janela e agir — o aviso de aprovação aparece em toda ação mutante:
+
+```
+> Abra o Bloco de Notas, digite "olá" e leia de volta o que está na tela.
+```
+
+## Instalação e desinstalação
+
+- **Canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-click#main"` — o script `prepare` compila apenas com dependências de produção.
+- **Canal npm** (versões publicadas): `dsh plugin --profile web add dsh-click`.
+- **Canal tarball**: `pnpm pack` neste repositório e então `dsh plugin --profile web add ./dsh-click-<version>.tgz`.
+- **Desinstalar**: `dsh plugin --profile web remove dsh-click` (ou remova a linha do patch do perfil).
+
+## Configuração
+
+Todos os ajustes são campos `Config` do Schemastery (alteráveis pelo cordis.yml). Uma sobrescrita direcionada por id substitui a linha inteira — redeclare cada chave que precisar. O `cordis.patch.yml` documenta cada chave em linha.
+
+| Chave | Padrão | Significado |
+|---|---|---|
+| `requireApproval` | `true` | Proteger toda ação mutante atrás da aprovação; observadores nunca perguntam |
+| `autoApproveWindows` | `[]` | Regex de título de janela/caminho de executável que pulam a pergunta de aprovação (ainda passam por atualidade e auditoria) |
+| `focusFallback` | `never` | Se uma ação pode trazer a janela alvo ao primeiro plano como último recurso (`never` / `allow`) |
+| `imageMode` | `auto` | Renderização do `screen_shot`: `auto` (imagem quando o modelo aceita imagens, texto caso contrário) ou `text` |
+| `helperTimeoutMs` | `30000` | Tempo limite por chamada ao helper em ms (1..300000) |
+| `maxHelperOutputBytes` | `25165824` | Limite de uma resposta do helper em bytes (1024..67108864) |
+| `maxScreenshotSide` | `2560` | Maior lado da captura em pixels (320..7680); capturas maiores são reduzidas |
+| `staleCheckPixels` | `true` | Comparar um hash de pixels novo antes de cada ação e recusar se mudou |
+| `maxObservationAgeMs` | `30000` | Idade máxima em ms de uma observação que uma ação pode citar (1000..600000) |
+| `maxCachedObservations` | `8` | Limite LRU de observações em cache (1..64) |
+| `maxElements` | `500` | Limite de elementos de acessibilidade por `screen_read` (1..2000) |
+| `maxTreeDepth` | `32` | Profundidade máxima do percurso da árvore de acessibilidade (1..64) |
+| `maxTextLength` | `200` | Comprimento de truncamento das strings visíveis ao modelo (16..10000) |
+| `rollbackEnabled` | `true` | Fazer backup e restaurar o texto do controle quando `type` falha |
+
+Exemplo de sobrescrita no patch do seu perfil:
+
+```yaml
+- insert:
+    - id: dsh-click
+      name: dsh-click
+      config:
+        requireApproval: true
+        autoApproveWindows: ['^Notepad']
+        focusFallback: never
+```
+
+## Ferramentas e superfícies
+
+| Ferramenta | Somente leitura | Requer aprovação | Notas |
+|---|---|---|---|
+| `screen_shot` | ✅ | — | Retorna um `observationId` que ações posteriores citam em `basedOn`; anexo de imagem quando o modelo aceita imagens |
+| `screen_read` | ✅ | — | Árvore de acessibilidade + dicas de pixels; os ids de elementos são o endereçamento das ações |
+| `click` | | ✅ | Exatamente um de `elementId` ou `(x, y)`; prefere UIA invoke, com mensagens postadas como fallback |
+| `type` | | ✅ | Somente elementos com padrão de valor; faz backup e restaura o texto do controle em falha |
+| `scroll` | | ✅ | Elemento (padrão scroll) ou janela (roda postada) |
+| `key` | | ✅ | Combinações de teclas postadas (`"Ctrl+S"`); apps que ignoram entrada postada recusam em voz alta |
+| `app_list` | ✅ | — | Aplicativos em execução e suas janelas visíveis |
+| `app_launch` | | ✅ | Por nome ou caminho do executável, com argumentos opcionais |
+
+## Permissões e dados
+
+- **Permissões**: ações mutantes cruzam a costura oficial `ctx.approval` — o plugin nunca a reimplementa nem a contorna. A lista de permissão apenas *pula a pergunta para janelas específicas*; não pode desativar as verificações de atualidade nem de identidade do processo.
+- **Dados**: o plugin não grava nada em disco além das capturas mantidas pelo armazenamento de anexos (endereçadas por conteúdo, sob a política de anexos do harness). Observações ficam em memória (LRU limitado). Sem requisições de rede, sem armazenamento de credenciais.
+- **Registro de sessão**: `dsh-click/observed` e `dsh-click/action` são eventos de auditoria somente-registro com fatos sanitizados de janela/processo — títulos, caminhos e texto livre são redigidos e truncados antes de serem gravados ou exibidos.
+
+## Limites de segurança
+
+- **Observe antes de agir, sempre.** Ações devem citar uma observação atual; uma tela mudada (hash de pixels) ou uma observação expirada é recusada com um motivo legível pelo modelo exigindo nova observação.
+- **Aprovação é o padrão.** `requireApproval: true` a menos que você libere explicitamente janelas específicas; toda ação — liberada ou não — é auditada.
+- **Sem roubo de foco.** O helper nunca traz a janela alvo ao primeiro plano (`focusFallback: 'never'` por padrão); a entrada é entregue via UIA ou mensagens postadas para não perturbar janelas em segundo plano.
+- **A identidade do processo é reverificada** imediatamente antes e depois de cada ação; uma troca de processo no meio faz o resultado falhar (`PROCESS_CHANGED`).
+- **Saída sanitizada.** Caracteres de controle são removidos, tabulações colapsam e valores com forma de credencial (chaves, tokens, JWT, cabeçalhos bearer) são redigidos antes de chegar ao modelo ou ao registro.
+- **Falha fechada.** Plataformas não suportadas, um serviço de subprocesso ausente ou um helper indisponível recusam cada chamada em voz alta — perfis continuam inicializando em todo lugar.
+
+## Limitações conhecidas
+
+- **Windows primeiro.** Os backends macOS e Linux estão reservados; nessas plataformas cada chamada falha fechado com um motivo claro.
+- **Fidelidade somente texto.** O `screen_read` depende de o aplicativo expor UIAutomation; apps sem árvore acessível oferecem apenas dicas de pixels. Cliques por coordenadas continuam disponíveis.
+- **Apps de entrada postada.** Alguns aplicativos ignoram mensagens de janela postadas (jogos, algumas superfícies Electron); o `key` informa isso com honestidade em vez de fingir sucesso.
+- **Auditoria de sessão em builds mais novos.** Os eventos de auditoria usam a forma de dois argumentos de `Session.append` (os peers fixados `0.1.0-rc.6` não têm opção de envelope de append); em builds pós-rc.6 os eventos são required-on-read, o que não é problema enquanto este plugin estiver instalado, pois ele declara esses tipos de evento.
+
+## Desenvolvimento
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc: src + tests contra o checkout local do harness
+pnpm run typecheck:ci  # tsc contra os tipos publicados 0.1.0-rc.6 (sem paths)
+pnpm test           # vitest: 56 testes, 8 suítes (o smoke do helper roda no Windows)
+pnpm run build      # bundle tsdown + declarações tsc (lib/)
+pnpm run verify:self-contained  # especificações de dependências resolvem pelo registry
+pnpm run verify:artifacts       # face ESM construída + helper nativo presentes
+pnpm pack           # o tarball publicado
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `computer-use`, `windows-automation`, `uiautomation`, `desktop-control`, `screen-reader`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: superfície de ferramentas, fronteira de segurança das ações, helper nativo do Windows, sanitizadores e a documentação em cinco idiomas.
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-click contributors

package/README.zh.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# 🖱️ dsh-click
+
+**DeepSeek Harness 的跨平台原生桌面控制 —— Windows 优先。**
+
+*先看清屏幕，再动手 —— 每次点击都过审批，每次操作都留审计。*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-click/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-click/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-click?label=version)](https://github.com/PerryLink/dsh-click/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-click)](https://www.npmjs.com/package/dsh-click)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-click)](https://www.npmjs.com/package/dsh-click)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## 兼容性
+
+| 方面 | 状态 |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6`（声明兼容 `0.1.0-rc.5`–`0.1.0-rc.6`） |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| 平台 | **Windows 优先**（UIAutomation + Win32 输入，经由内置 PowerShell 辅助进程）；macOS/Linux 后端已预留，失败时以明确原因关闭 |
+| 模型 | 纯文本模型完整可用（`screen_read` 输出结构化文本）；视觉模型额外获得 `screen_shot` 图像 |
+
+## 你能得到什么
+
+`dsh-click` 为 harness 提供完整的「观察 → 行动」闭环，作用于原生桌面应用：
+
+- **`screen_shot`** —— 截取窗口（或主屏幕）截图，按可配置上限缩放。视觉模型会附带图像；纯文本模型则获得文字描述，照常可用。
+- **`screen_read`** —— 结构化观察：窗口的无障碍树（元素 id、类型、名称、矩形、支持的模式）加像素位置提示与颜色 —— 纯文本，无需图像模型。
+- **`click` / `type` / `scroll` / `key`** —— 以元素 id 或坐标寻址的窗口级操作。优先 UIA invoke，回退到 post 窗口消息 —— 且**绝不抢占前台焦点**。
+- **`app_list` / `app_launch`** —— 枚举运行中的应用及其窗口；按名称或路径启动应用。
+
+每个变更性操作都穿过同一条安全边界：
+
+1. **新鲜度** —— 操作必须引用 `basedOn` 观察；执行前重新捕获窗口，屏幕变化（像素哈希 + 最大时限）即拒绝。
+2. **审批** —— 默认经 `ctx.approval` 门禁；可用窗口标题/可执行路径正则放行特定窗口（仍记录审计）。
+3. **进程身份** —— 操作前后分别校验所属进程 pid 与可执行路径；发生变化即大声拒绝。
+4. **审计** —— 观察与操作以 `dsh-click/observed` / `dsh-click/action` 事件写入会话日志（脱敏、仅日志）。
+
+```text
+模型                           harness
+  │ screen_read ──▶ observationId (+ 元素、像素)              ← 结构化文本
+  │ click {basedOn, target} ──▶ 新鲜度校验 ──▶ 审批 ──▶ helper (UIA)
+  │                             像素哈希变化? ── 拒绝并要求重新观察
+  │                             操作后 pid/exe 变化? ── PROCESS_CHANGED
+  │ ◀── 规范 JSON + 审计事件 (dsh-click/action)
+```
+
+## 快速开始
+
+```sh
+# 1. 把 bundle 装进你的 profile
+dsh plugin --profile web add "github:PerryLink/dsh-click#main"
+
+# 或从 npm 安装（正式发布版）
+dsh plugin --profile web add dsh-click
+
+# 2. 重启并核实行
+dsh --profile web --dump-config | grep -A2 'id: dsh-click'
+```
+
+然后让 agent 观察窗口并操作 —— 每次变更性操作都会弹出审批：
+
+```
+> 打开记事本，输入 "hello"，再读回屏幕上的内容。
+```
+
+## 安装与卸载
+
+- **git 通道**（最新 `main`）：`dsh plugin --profile web add "github:PerryLink/dsh-click#main"` —— `prepare` 脚本仅用生产依赖构建。
+- **npm 通道**（正式发布版）：`dsh plugin --profile web add dsh-click`。
+- **tarball 通道**：在本仓库执行 `pnpm pack`，然后 `dsh plugin --profile web add ./dsh-click-<version>.tgz`。
+- **卸载**：`dsh plugin --profile web remove dsh-click`（或从 profile patch 中删除该行）。
+
+## 配置
+
+所有可调项都是 Schemastery `Config` 字段（可在 cordis.yml 中修改）。按 id 定向覆盖会替换整行 —— 需要重新声明每个键。`cordis.patch.yml` 内联说明了每个键。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `requireApproval` | `true` | 每个变更性操作都过审批；观察类工具从不询问 |
+| `autoApproveWindows` | `[]` | 跳过审批询问的窗口标题/可执行路径正则（仍做新鲜度校验并审计） |
+| `focusFallback` | `never` | 操作是否可在最后手段下把目标窗口带到前台（`never` / `allow`） |
+| `imageMode` | `auto` | `screen_shot` 渲染：`auto`（模型支持图像时附图像，否则文字）或 `text` |
+| `helperTimeoutMs` | `30000` | 每次 helper 调用的超时（毫秒，1..300000） |
+| `maxHelperOutputBytes` | `25165824` | 单次 helper 响应的字节上限（1024..67108864） |
+| `maxScreenshotSide` | `2560` | 截图最长边像素（320..7680）；超出即缩放 |
+| `staleCheckPixels` | `true` | 每次操作前对比新像素哈希，变化即拒绝 |
+| `maxObservationAgeMs` | `30000` | 操作可引用观察的最大时限（毫秒，1000..600000） |
+| `maxCachedObservations` | `8` | 观察缓存 LRU 上限（1..64） |
+| `maxElements` | `500` | 每次 `screen_read` 的无障碍元素上限（1..2000） |
+| `maxTreeDepth` | `32` | 无障碍树遍历最大深度（1..64） |
+| `maxTextLength` | `200` | 脱敏后模型可见字符串的截断长度（16..10000） |
+| `rollbackEnabled` | `true` | `type` 失败时备份并还原控件文本 |
+
+profile patch 中的覆盖示例：
+
+```yaml
+- insert:
+    - id: dsh-click
+      name: dsh-click
+      config:
+        requireApproval: true
+        autoApproveWindows: ['^Notepad']
+        focusFallback: never
+```
+
+## 工具与界面
+
+| 工具 | 只读 | 需要审批 | 说明 |
+|---|---|---|---|
+| `screen_shot` | ✅ | — | 返回 `observationId` 供后续操作在 `basedOn` 中引用；模型支持图像时附带图片 |
+| `screen_read` | ✅ | — | 无障碍树 + 像素提示；元素 id 是操作的寻址方式 |
+| `click` | | ✅ | `elementId` 与 `(x, y)` 二选一；优先 UIA invoke，回退 post 消息 |
+| `type` | | ✅ | 仅限 value 模式元素；失败时备份并还原控件文本 |
+| `scroll` | | ✅ | 元素（scroll 模式）或窗口（post 滚轮） |
+| `key` | | ✅ | post 按键组合（`"Ctrl+S"`）；忽略 post 输入的应用会大声拒绝 |
+| `app_list` | ✅ | — | 运行中的应用及其可见窗口 |
+| `app_launch` | | ✅ | 按名称或可执行路径启动，可带参数 |
+
+## 权限与数据
+
+- **权限**：变更性操作走官方 `ctx.approval` 接缝 —— 插件从不重实现或绕过它。白名单只会*对特定窗口跳过询问*，不能关闭新鲜度或进程身份校验。
+- **数据**：除 attachment store 保存的截图（内容寻址、受 harness 自身附件策略约束）外，插件不落盘任何东西。观察仅存内存（有界 LRU）。无网络请求，不存凭据。
+- **会话日志**：`dsh-click/observed` 与 `dsh-click/action` 是仅日志的审计事件，携带脱敏后的窗口/进程事实 —— 标题、路径与自由文本在写入或展示前均先脱敏并截断。
+
+## 安全边界
+
+- **先观察后行动，每次如此。** 操作必须引用新鲜观察；屏幕变化（像素哈希）或观察过期即拒绝，并以模型可读的原因要求重新观察。
+- **审批是默认。** 除非你显式放行特定窗口，否则 `requireApproval: true`；每次操作 —— 无论放行与否 —— 都记录审计。
+- **不抢前台焦点。** helper 从不把目标窗口带到前台（默认 `focusFallback: 'never'`）；输入经 UIA 或 post 消息送达，不打扰后台窗口。
+- **进程身份前后复验。** 每个操作前后立即校验进程身份；操作中途进程被替换则判失败（`PROCESS_CHANGED`）。
+- **输出脱敏。** 控制字符被剥离、制表符折叠、凭据形态内容（密钥、token、JWT、bearer 头）在到达模型或日志前一律打码。
+- **失败关闭。** 不支持的平台、缺失的 subprocess 服务或不可用的 helper 都会大声拒绝每个调用 —— profile 在任何地方都能正常启动。
+
+## 已知限制
+
+- **Windows 优先。** macOS 与 Linux 后端已预留；在这些平台上每次调用都以明确原因失败关闭。
+- **纯文本保真度。** `screen_read` 依赖应用暴露 UIAutomation；没有无障碍树的应用只有像素提示。坐标点击仍然可用。
+- **post 输入类应用。** 部分应用忽略 post 窗口消息（游戏、部分 Electron 界面）；`key` 会如实报告而非假装成功。
+- **较新 harness 构建上的会话审计。** 审计事件使用两参数 `Session.append` 形式（钉住的 `0.1.0-rc.6` peers 没有 append envelope 选项）；在 post-rc.6 构建上事件为 required-on-read，只要安装了本插件即无碍，因为本插件声明了这些事件类型。
+
+## 开发
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc：src + tests，对照本地 harness checkout
+pnpm run typecheck:ci  # tsc：对照已发布的 0.1.0-rc.6 类型（无 paths）
+pnpm test           # vitest：56 个测试、8 个套件（helper 冒烟在 Windows 上运行）
+pnpm run build      # tsdown bundle + tsc 声明（lib/）
+pnpm run verify:self-contained  # 依赖声明全部来自 registry
+pnpm run verify:artifacts       # 构建产物 ESM 面 + 原生 helper 齐全
+pnpm pack           # 发布用 tarball
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `computer-use`, `windows-automation`, `uiautomation`, `desktop-control`, `screen-reader`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) —— 创建者与维护者：工具面、操作安全边界、Windows 原生 helper、脱敏层与五语文档。
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-click contributors

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security vulnerabilities.
+
+Report privately through GitHub's private vulnerability reporting:
+
+**https://github.com/PerryLink/dsh-click/security/advisories/new**
+
+That flow keeps the report confidential while we triage, and it is the channel we watch first.
+
+## Before you report
+
+- **Redact sensitive data** from any logs, screenshots, window titles, or session excerpts you attach: tokens, API keys, secrets, Authorization/request headers, personal paths, and account identifiers. Trimmed accessibility trees and stack traces are usually enough.
+- Include, when possible: the plugin version, the harness (`dsh`) version, Node and OS versions, and the minimal steps to reproduce.
+
+## What to expect
+
+- **Acknowledgment**: within 5 business days.
+- **Triage**: within 10 business days we confirm the issue and assess severity, or ask for more details.
+- **Fix**: security fixes are prepared in a private fork, released as a patch version, and announced in the release notes.
+
+## Disclosure and credit
+
+- We follow coordinated disclosure: a public advisory (and CVE request where appropriate) is published once a fix ships.
+- Reporters are credited in the advisory unless they ask to remain anonymous. There is no bug bounty program at this time.
+
+## Scope
+
+This plugin controls native desktop windows from inside the harness: it observes windows (screenshot, accessibility tree) and performs window-scoped actions (click/type/scroll/key/launch) gated by approval. Its own guarantees are:
+
+- Mutating actions require a fresh observation and approval (or an explicit window allowlist), and verify the target process identity before and after acting.
+- Actions never bring a window to the foreground by default (`focusFallback: 'never'`).
+- Everything shown to the model or written to the session log is sanitized (secrets redacted, control characters stripped, length-capped).
+- The plugin makes no network requests and stores no credentials; API keys or tokens only ever appear if the model itself passes them through a tool argument, and the audit trail redacts credential-shaped values.
+
+Vulnerabilities in the harness itself should be reported to the official harness maintainers instead.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third-party notices
+
+`dsh-click` bundles no third-party source code. The native helper
+(`native/win32/dsh-click-helper.ps1`) and all TypeScript/JavaScript sources in
+this repository are original works by the dsh-click contributors, licensed
+under Apache-2.0 (see `LICENSE`).
+
+The package depends on the following software. None of it is bundled into the
+published tarball; these are install-time dependencies:
+
+| Package | Version range | License | Purpose |
+|---|---|---|---|
+| [tsdown](https://github.com/rolldown/tsdown) | `^0.22.14` | MIT | Build-time bundling of `lib/` (a regular dependency so the git-install channel's `prepare` script can build) |
+| [typescript](https://github.com/microsoft/TypeScript) | `^5.9.0` | Apache-2.0 | Build-time declaration emission (`lib/types/`) |
+| [@deepseek-ai/cordis](https://www.npmjs.com/package/@deepseek-ai/cordis) | `^4.0.1` (peer) | See package | The plugin runtime |
+| [@deepseek-ai/schemastery](https://www.npmjs.com/package/@deepseek-ai/schemastery) | `^3.18.0` (peer) | See package | Configuration schema |
+| `@deepseek-ai/dsh-*` peers | `0.1.0-rc.6` (peer) | See packages | Official harness seams (`dsh-tools`, `dsh-session`, `dsh-subprocess`, `dsh-llm`, `dsh-attachment`, `dsh-agent`, `dsh-user-approval`) |
+
+At runtime the plugin only talks to the harness services listed as
+peerDependencies; it performs no network requests of its own.

package/cordis.patch.yml

@@ -0,0 +1,53 @@
+# dsh-click bundle patch: mount the desktop-control plugin.
+#
+# Every key below is a Config field (Schemastery schema); invalid values fail
+# the profile load loudly. See README.md "Configuration" for the full table.
+- insert:
+    - id: dsh-click
+      name: dsh-click
+      config:
+        # Gate every mutating action (click/type/scroll/key/app_launch) behind
+        # approval. Observers (screen_shot/screen_read/app_list) never ask.
+        requireApproval: true
+        # Window title or executable-path regexes that skip the approval ask.
+        # The action still runs through the freshness and process-identity
+        # checks and is audit-logged. Empty = ask for every action.
+        autoApproveWindows: []
+        # Whether a mutating action may bring the target window to the
+        # foreground as a fallback when posted input is unavailable.
+        # 'never' (default) never steals focus; 'allow' permits the fallback.
+        focusFallback: never
+        # How screen_shot renders: 'auto' attaches an image when the current
+        # model accepts images and a text description otherwise; 'text' always
+        # returns the text-only description (for text-only models).
+        imageMode: auto
+        # Per-helper-call timeout in milliseconds (1..300000).
+        helperTimeoutMs: 30000
+        # Cap on one helper response in bytes (1024..67108864); PNG
+        # screenshots are base64-heavy.
+        maxHelperOutputBytes: 25165824
+        # Longest side of a captured screenshot in pixels (320..7680); larger
+        # captures are downscaled.
+        maxScreenshotSide: 2560
+        # Compare a fresh pixel hash of the target window before every action
+        # and refuse when it differs from the cited observation (the
+        # stale-state boundary). Disable only for tooling that mutates the
+        # screen faster than the check can run.
+        staleCheckPixels: true
+        # Maximum age in ms of an observation that an action may still base
+        # on (1000..600000). Older observations are refused and must be
+        # re-observed.
+        maxObservationAgeMs: 30000
+        # Cap on cached observations (1..64), LRU-evicted. Actions address
+        # observations by the id returned from screen_shot/screen_read.
+        maxCachedObservations: 8
+        # Cap on accessibility elements one screen_read returns (1..2000).
+        maxElements: 500
+        # Maximum depth of the accessibility tree walk (1..64).
+        maxTreeDepth: 32
+        # Truncation length for sanitized model-visible strings (16..10000):
+        # window titles, executable paths, element names.
+        maxTextLength: 200
+        # Back up and restore control text when `type` fails (true = restore
+        # the original text; false = leave the partially typed text).
+        rollbackEnabled: true