|
### 🖼️ Pré-visualizações Exatas de Múltiplos Quadros
O exportador headless do OpenPencil instalado gera pré-visualizações fiéis ao design: o primeiro quadro de nível superior como um PNG grande e seguro para repetição, além de uma faixa de miniaturas com rolagem horizontal, clique para selecionar e navegação anterior/próxima para documentos com vários quadros.
|
### 🗺️ Canvas Interativo
"Abrir canvas interativo" monta de forma preguiçosa o Web SDK somente leitura do OpenPencil com pan, zoom e ajuste à tela — inspecione qualquer página, nó aninhado ou página inativa sem sair da conversa.
|
|
### ✏️ Editor Gerenciado
Com `editable: true`, a ação de edição abre o editor gerenciado do OpenPencil — seleção, camadas, propriedades, ferramentas de desenho, desfazer/refazer e semântica explícita de salvamento — em um workbench direito redimensionável com opção de tela cheia.
|
### 🤖 Ferramentas de Design Nativas de Agente
Cinco ferramentas diretas de canvas e seis ferramentas `openpencil_pipeline_*` permitem que o Agente crie, inspecione, refine, publique, modifique e leia um canvas real por meio dos runtimes gerenciados do OpenPencil.
|
|
### 🔐 Concessões Controladas por Capacidades
As concessões de imagem e documento são capacidades assinadas e vinculadas a hash. Os metadados do navegador nunca expõem um caminho arbitrário do host, e as capacidades assinadas de pré-visualização/edição nunca entram no resultado canônico da ferramenta nem no contexto do modelo.
|
### ⚡ Segurança Transacional
Um documento do pipeline completo permanece como rascunho privado e não publicado até passar por todas as barreiras de qualidade nativas e do DSH. A publicação não sobrescreve caminhos existentes, e cancelamentos ou lotes com falha não deixam um destino vazio.
|
|
### 🌍 Segue o Visual do DSH
O cartão da ferramenta e o editor gerenciado seguem a localização chinês/inglês do DSH e o tema claro/escuro sem recarregar a sessão de edição.
|
### 🎯 Um Fluxo de Trabalho Completo
"Requisito → rascunho privado → lotes semânticos → prévias live para o usuário → validação determinística de estrutura/layout/qualidade → publicação atômica com integridade do PNG final" — um fluxo completo dentro do DSH.
|
## Instalação no DSH
O DSH é um pacote separado. Instale-o uma vez, se ainda não tiver:
```sh
npm install -g @deepseek-ai/dsh@latest
```
Depois adicione o plugin a um perfil e inicie o app web:
```sh
dsh plugin --profile web add @zseven-w/dsh-openpencil@next
dsh web
```
Para desenvolvimento local, compile este checkout, vincule seu caminho absoluto ao perfil Web e reinicie completamente o DSH:
```sh
pnpm run build
dsh plugin --profile web add link:/absolute/path/to/dsh-openpencil
dsh web
```
A dependência `link:` torna recompilações posteriores visíveis a partir deste checkout. No entanto, o DSH deve ser totalmente reiniciado após substituir a dependência do perfil, pois o perfil Web fornecido não faz hot reload dos bundles do host por padrão.
Prefere não instalar o DSH globalmente? Rode os mesmos dois passos via `pnpm dlx`:
```sh
pnpm dlx --package=@deepseek-ai/dsh@latest dsh plugin --profile web add @zseven-w/dsh-openpencil@next
pnpm dlx --package=@deepseek-ai/dsh@latest dsh web
```
> O plugin do OpenPencil é público e não exige token npm. Se a pré-versão do DSH em si exigir autenticação de registro, mantenha essa credencial em um config npm no nível do usuário ou temporário, fora do checkout. Este repositório não contém intencionalmente nenhuma credencial de registro.
## Ferramentas de Design
A seleção opcional segue `openpencil_style_plan` → `openpencil_style_confirm` → `openpencil_pipeline_begin`, com o brief original e `style_selection`. Catálogo e guia exato funcionam sem recomendação; o provedor fica desligado por padrão. A passagem suporta script, não app-agent nem comércio. A geração app-agent normal continua disponível.
| Ferramenta | O que ela faz |
| --- | --- |
| `openpencil_new` | Caminho rápido compatível para tarefas simples: executa um script QuickJS transacional de `batch_design`, publica apenas se o destino não existir e retorna uma apresentação editável. Prefira o pipeline completo para design de produção. |
| `openpencil_pipeline_begin` | Inicia um rascunho privado da sessão, cria internamente sua única raiz, retorna o contrato compacto de canvas/build compatível com o runtime e abre imediatamente o mesmo rascunho live na barra lateral; o `.op` de destino continua não publicado. |
| `openpencil_pipeline_context` | Carrega apenas um detalhe direcionado de diretriz, estilo, tema ou UI kit que realmente esteja ausente do contrato de begin; não é uma etapa fixa de inicialização. |
| `openpencil_pipeline_batch` | Executa no máximo dois scripts nativos diretos de geração `I(...)`/`K(...)`: primeiro o viewport inicial limitado por `begin.next`, depois todas as regiões restantes em um segundo e último lote. Cada transação bem-sucedida tenta mostrar ao usuário um PNG exato. |
| `openpencil_pipeline_inspect` | Fornece diagnóstico manual somente quando o usuário o solicita explicitamente; a geração normal não o usa como prévia nem como revisão visual do modelo. |
| `openpencil_pipeline_finish` | Em uma chamada saudável, finaliza e valida o rascunho, renderiza automaticamente a prévia PNG exata da raiz final e publica atomicamente com `createIfAbsent`. Apenas um reparo exclusivamente `U(...)` e um finish final são autorizados quando o resultado é `needs_correction`, `canContinue: true`, traz `repairTargets` completos e não vazios e `omitted: 0`; qualquer outro resultado não publicado é terminal. |
| `openpencil_pipeline_abort` | Descarta o rascunho não publicado sem criar o arquivo de destino. |
| `openpencil_create` | Aplica um programa transacional `batch_design` para gerar ou reestruturar nós em um canvas ao vivo existente. |
| `openpencil_edit` | Modifica um nó explícito ou o único nó selecionado pelo usuário. |
| `openpencil_render` | Cria um snapshot `.op` imutável e endereçado por conteúdo e renderiza todos os quadros de nível superior da página ativa — com `scale` e `editable` opcionais. |
| `openpencil_selection` | Lê exatamente os nós selecionados no canvas ao vivo do editor. |
## Fluxo de Trabalho de Design do Agente
Para um pedido curto comum, chame `openpencil_pipeline_begin` imediatamente e siga o caminho rápido fixo: o primeiro lote JS direto limitado por `begin.next` → um segundo e último lote JS direto com todas as regiões restantes → uma chamada a `openpencil_pipeline_finish`. Begin cria a única raiz e abre imediatamente o canvas privado live na barra lateral; o caminho solicitado no workspace permanece ausente até a publicação atômica. Depois de cada begin ou lote bem-sucedido, faça imediatamente a próxima chamada exigida sem narração, planejamento, comparação, inspeção ou ferramenta não relacionada. Por padrão, o design inteiro usa exatamente uma imagem; cada frame Hero/Product/Art/Media possui um único visual principal, nunca uma imagem junto de um ícone placeholder.
Depois de cada lote aplicado com sucesso, a ferramenta apenas tenta apresentar ao usuário uma prévia PNG exata. Assim que a chamada retornar, siga imediatamente seu `next`; não espere por uma autoinspeção visual do modelo. Se `next` informar `previewUnavailable`, o script já foi confirmado no canvas live: não execute o lote novamente nem chame `openpencil_pipeline_inspect` ou `read_image`. `openpencil_pipeline_inspect` fica reservado exclusivamente para um diagnóstico solicitado explicitamente pelo usuário.
Finish executa as verificações determinísticas nativas de finalização, lint, contraste e layout, além das barreiras rígidas de qualidade do DSH. Uma chamada saudável renderiza o PNG exato da raiz final e publica na mesma etapa. Um reparo só é autorizado quando o resultado contém ao mesmo tempo `stage: "needs_correction"`, `canContinue: true`, `repairTargets` completos e não vazios com `omitted: 0`, e cada alvo traz `operation: "U"`, um `nodeId` exato e não vazio e um `patch` não vazio. Aplique todos os alvos juntos em exatamente um lote somente `U(...)` e, sem narração, chame finish exatamente mais uma vez. Qualquer outro resultado não publicado, erro ou `canContinue: false` é terminal: informe uma vez e não tente novamente, inspecione, leia imagem/contexto, aborte ou inicie outro rascunho. Com `published: true`, o PNG final e o editor live já estão anexados: retorne o resultado e encerre imediatamente. Uma barreira com falha ou `openpencil_pipeline_abort` mantém o destino ausente. A concessão editável do documento só abre automaticamente a barra lateral quando ela está livre e mantém **Editar tela** para uma troca explícita.
Dentro do mesmo serviço DSH em execução, trocar de navegador ou recarregar permite recuperar uma publicação durável e analisada estritamente de `openpencil_new` ou `openpencil_pipeline_finish` como o PNG exato com a ação explícita **Editar tela**. Um cartão histórico nunca abre automaticamente a barra lateral; o usuário precisa clicar nessa ação. Um `openpencil_render` histórico comum permanece somente leitura, e conexões não-loopback nunca recebem uma concessão de editor.
A skill `openpencil-design` incluída continua sendo uma referência leve opcional; a geração comum começa diretamente com o contrato compacto completo de begin. O schema nativo atual é autoritativo, e o runtime gerenciado não depende do binário de desktop. `openpencil_new` permanece como um caminho rápido compatível de lote único.
Use `openpencil_create` e `openpencil_edit` somente para um canvas ao vivo existente. As edições permanecem não salvas até a ação Salvar do editor.
## Recursos do Visualizador Web
O DSH serve apenas `client.js` para um plugin de cliente, então o ESM SDK do OpenPencil, seu WASM e o CanvasKit são preparados como recursos explícitos de mesma origem:
```sh
pnpm run sync:viewer-assets
```
O comando de sincronização prefere um checkout irmão `../openpencil` (desenvolvimento local), recorrendo ao submódulo fornecido `vendor/openpencil` (CI e clones novos). Substitua-o com `OPENPENCIL_ROOT` ou `--openpencil-root`. Um diretório de recursos pré-compilado completo pode ser selecionado com `DSHPLUGIN_OPENPENCIL_VIEWER_SOURCE`. A busca em tempo de execução pode ser substituída com `DSHPLUGIN_OPENPENCIL_VIEWER_ASSET_DIR`.
Os recursos do visualizador são carregados de forma preguiçosa somente depois que o usuário abre o canvas. Se estiverem ausentes ou inválidos, a pré-visualização em PNG permanece disponível e nenhum botão de canvas é anunciado.
## Editor Gerenciado
As sessões editáveis usam o host web gerenciado do OpenPencil — a mesma arquitetura usada pelo `op-vscode`. O plugin inicia o host somente após uma ação autorizada do usuário, mantém o token do daemon na memória, valida a origem e o src do iframe e encerra o processo quando a sessão do editor termina. A superfície do editor é selecionada progressivamente: detalhes nativos da ferramenta quando o host declara essa costura; caso contrário, o workbench direito do plugin com controles de redimensionamento e tela cheia.
A inicialização usa um listening handshake seguro para montagens lentas: as verificações de prontidão começam somente depois que o host incluído anuncia seu endereço vinculado. Nenhuma instalação desktop do OpenPencil é necessária.
As instalações publicadas oferecem seis destinos nativos: `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64` e `win32-x64`; os pacotes Linux exigem glibc. O pacote raiz seleciona o pacote de plataforma adequado ao sistema operacional e à CPU por meio de `optionalDependencies` com versões exatas (por exemplo, `@zseven-w/dsh-openpencil-darwin-arm64`). Esse pacote fornece `op-host-web-server`, o bundle web do editor e o CanvasKit como um único runtime compatível. Portanto, o editor gerenciado não depende de `/Applications/OpenPencil.app`, de `openpencil-desktop` no `PATH` nem de um checkout do código-fonte do OpenPencil.
Se o DSH recarregar ou descarregar o plugin enquanto o canvas estiver sujo, o host mantém um rascunho de recuperação local opaco por até sete dias. Reabrir a mesma fonte pergunta antes de restaurá-la no canvas ao vivo; a recuperação nunca sobrescreve o arquivo `.op` até que o usuário salve explicitamente.
Os pacotes oficiais das seis plataformas recebem seus endpoints de bootstrap de colaboração para China e Global durante o build de release protegido, que valida os valores injetados antes da publicação. Um build local próprio sem essa injeção pode substituir o bootstrap antes de iniciar o DSH com `OPENPENCIL_COLLAB_BOOTSTRAP_URL=https://
Junte-se ao nosso Discord
— Tire dúvidas, compartilhe designs e sugira recursos.
**Comunidade reconhecida: [LINUX DO](https://linux.do/)**
## Licença
[MIT](./LICENSE) — Copyright (c) 2026 ZSeven-W
Os componentes de terceiros estão listados em [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).