---

Compatibilidade

Superfície	Status
Harness	DeepSeek Harness 0.1.1-rc.2
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).

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

# 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).

Se o pnpm reportar ERR_PNPM_IGNORED_BUILDS para este pacote (a validação inofensiva do binário de plataforma do esbuild), adicione allowBuilds: { esbuild: true } ao seu pnpm-workspace.yaml — o CLI dsh imprime o trecho exato.

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)
auditSessionEvents	true	Acrescenta eventos de auditoria dsh-click/observed/dsh-click/action à sessão. A porta adaptativa já omite o append em hosts sem envelope (rc.6–rc.8, 0.1.1-rc.2 e 0.1.2-alpha.1, que falha fechado para tipos desconhecidos na leitura); defina false para interromper totalmente os appends de 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
ocr.enabled / command / language	true / tesseract / eng	OCR opcional para screen_find (detectado na montagem; degrada para indisponível sem tesseract)

Exemplo de sobrescrita no patch do seu perfil:

- 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 do harness sem envelope. Os eventos de auditoria cruzam uma porta adaptativa: hosts que conhecem o vocabulário acrescentam diretamente, hosts com o envelope ignorable acrescentam com o marcador, e hosts sem envelope — 0.1.0-rc.6–0.1.0-rc.8, 0.1.1-rc.2 e 0.1.2-alpha.1 (que removeu o envelope e falha fechado para tipos desconhecidos na leitura) — não recebem append de auditoria; os resultados das ferramentas continuam sendo a trilha reconstruível. Defina auditSessionEvents: false para interromper os appends por completo.

Desenvolvimento

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.1-rc.2 (sem paths)
pnpm test           # vitest: 66 testes, 11 arquivos (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 — 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.
• @Mchsd — adicionou a opção auditSessionEvents para harnesses cujo leitor de sessão rejeita os eventos de auditoria do dsh-click (#2).

PerryLink DSH Plugin Family

Este projeto é um dos 33 plugins de DeepSeek Harness mantidos por PerryLink. Se este ajuda você, os outros provavelmente também:

Plugin	One-liner
dsh-dsh-auto-review	Auto-revisão de segundo modelo na cadeia de aprovação, com falha fechada por padrão
dsh-dsh-background-agents	Agentes filhos em segundo plano duráveis com barra lateral de UI web, mensagens e interrupção
dsh-dsh-budget	Governança de custos para DeepSeek Harness: orçamentos, carbono e latência em um painel.
dsh-dsh-checkpoint-rewind	Equivalente ao /rewind do Claude Code: instantâneos, bifurcações de sessão, restauração de uso único
dsh-dsh-claude-move	Migre sessões, memória, habilidades e CLAUDE.md do Claude Code para o DSH
dsh-dsh-composer-history	Histórico de entrada estilo terminal para o compositor web: setas, busca Ctrl+R
dsh-dsh-data-quality	Verificações de qualidade de datasets e verificação de citações (a ponte numérica opcional consumida aqui)
dsh-dsh-defend	Defesa contra injeção de prompt, jailbreak e vazamento de segredos para DeepSeek Harness.
dsh-dsh-doublecheck	Guardião de disciplina de engenharia: sabatina de requisitos, portões de teste, revisão adversária
dsh-dsh-draw	Roteamento unificado de geração de imagens estáticas para DeepSeek Harness.
dsh-dsh-fast	Diagnóstico de desempenho só de leitura para DeepSeek Harness.
dsh-dsh-fund-research	Relatórios de pesquisa deterministas para fundos mútuos públicos chineses
dsh-dsh-github	Integração de PR/issues do GitHub para o DSH, cada escrita controlada por aprovação
dsh-dsh-industry-research	Orquestração de pesquisa setorial que sela as suas entregas através do ctx.researchReport.assemble deste plugin
dsh-dsh-library	Base de conhecimento documental local para DeepSeek Harness.
dsh-dsh-local-ai	Integração de modelos locais (Ollama) para DeepSeek Harness.
dsh-dsh-lsp-actions	Diagnósticos, formatação, autocompletar, ações de código e renomeação LSP sobre servidores de linguagem
dsh-dsh-mask	Middleware de mascaramento de PII: anonimiza no limite do modelo, restaura na camada de exibição
dsh-dsh-mcp-panel	Painel de tempo de execução MCP somente leitura: comando /mcp + aba Settings com status, ferramentas e erros
dsh-dsh-memento	Memória entre sessões controlada por aprovação: costura ctx.memory + SQLite + ferramenta de memória
dsh-dsh-observe	Exportador de observabilidade OpenTelemetry e Langfuse para DeepSeek Harness.
dsh-dsh-output-styles	Troca de estilo em tempo de execução equivalente ao outputStyles do Claude Code
dsh-dsh-permission-rules	Regras de permissão declarativas allow/deny/ask estilo Claude Code com auditoria
dsh-dsh-plugin-guide	Base de conhecimento de desenvolvimento de plugins como habilidade de agente sob demanda
dsh-dsh-research-report	Motor de relatórios de pesquisa verificáveis com evidência endereçada por conteúdo
dsh-dsh-score	Pontuação de qualidade multidimensional para plugins de DeepSeek Harness.
dsh-dsh-session-pin	Fixe sessões na barra lateral web com ordenação durável
dsh-dsh-session-sync	Sincronização de sessões entre dispositivos para DeepSeek Harness — um espelho git dedicado do seu armazenamento de sessões.
dsh-dsh-skill-pack-security	Pacote de habilidades de auditoria de segurança: varredura de segredos, revisão de dependências e cadeia de suprimentos
dsh-dsh-talk	Loop de sessão com voz para DeepSeek Harness: fale e ouça a resposta.
dsh-dsh-test-drive	Test drives isolados de instalação e smoke para plugins de DeepSeek Harness.
dsh-dsh-translate	Tradução de parâmetros entre fornecedores e reparo determinístico de JSON para DeepSeek Harness.

License

Apache License 2.0 © 2026 dsh-click contributors