Design do Modo Compacto: Análise Competitiva e Otimização

Alternância de modo compacto/verboso com Ctrl+O — análise competitiva com o Claude Code, revisão da implementação atual e recomendações de otimização.

Documentação do usuário: Configurações — ui.compactMode.

1. Resumo Executivo

O Qwen Code e o Claude Code oferecem um atalho Ctrl+O para alternar entre visualizações compacta e detalhada das saídas das ferramentas, mas a filosofia de design, estado padrão e modelo de interação diferem fundamentalmente. Este documento fornece uma comparação profunda em nível de código-fonte, identifica lacunas de UX e propõe otimizações para o Qwen Code.

2. Análise da Implementação do Claude Code

2.1 Arquitetura

O Claude Code usa uma abordagem baseada em tela em vez de uma alternância de renderização em nível de componente:

┌──────────────────────────────────┐
│         AppState (Zustand)       │
│  verbose: boolean (default: false)│
│  screen: 'prompt' | 'transcript' │
└──────────┬───────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  alterna o modo de tela
     │  Handler    │  NÃO é uma flag de renderização
     └─────┬──────┘
           │
     ┌─────▼──────────────┐
     │    REPL.tsx         │
     │  screen='prompt'  → visualização compacta (padrão)
     │  screen='transcript'→ visualização detalhada
     └────────────────────┘

2.2 Principais Arquivos de Código-Fonte

2.3 Decisões de Design

1. Compacto é o padrão. Os usuários veem uma interface limpa pronta para uso; os detalhes são opcionais.
2. Escopo da sessão. verbose volta para false em cada nova sessão — o Claude Code assume que os usuários geralmente preferem a visualização compacta e só precisam de detalhes temporariamente.
3. Alternância em nível de tela. Ctrl+O não altera como os componentes renderizam; ele alterna a exibição inteira entre uma tela “prompt” (compacta) e uma tela “transcript” (detalhada).
4. Sem snapshot congelado. Não existe o conceito de congelamento de snapshot. Ao alternar, a exibição é atualizada imediatamente com o estado atual.
5. Diálogos de permissão são separados. As aprovações de ferramentas são renderizadas em uma camada de sobreposição dedicada que nunca é afetada pela alternância verboso/compacto.
6. Dica por ferramenta. O componente CtrlOToExpand mostra uma dica contextual em ferramentas individuais quando produzem saída grande, suprimida em subagentes.

2.4 Fluxo do Usuário

Início da sessão → modo compacto (padrão)
     │
     ├─ Saídas das ferramentas são resumidas em uma única linha
     ├─ Saída grande da ferramenta mostra dica "(ctrl+o to expand)"
     │
     ├─ Usuário pressiona Ctrl+O
     │     └─→ Tela alterna para transcript (visualização detalhada)
     │         └─ Usuário vê toda a saída da ferramenta, pensamento, etc.
     │
     ├─ Usuário pressiona Ctrl+O novamente
     │     └─→ Tela alterna de volta para prompt (compacta)
     │
     └─ Sessão termina → verbose volta para false

3. Análise da Implementação do Qwen Code

3.1 Arquitetura

O Qwen Code usa uma flag de renderização em nível de componente que cada componente de UI lê do contexto:

┌─────────────────────────────────────┐
│      CompactModeContext             │
│  compactMode: boolean (default: false)│
│  setCompactMode: (v) => void        │
└──────────┬──────────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  alterna compactMode
     │  Handler    │  persiste em settings
     └─────┬──────┘
           │
     ┌─────▼──────────────────┐
     │  Cada componente lê    │
     │  compactMode e         │
     │  decide como renderizar │
     └────────────────────────┘
           │
     ┌─────▼──────────────────────────────┐
     │  ToolGroupMessage                   │
     │    showCompact = compactMode        │
     │      && !hasConfirmingTool          │
     │      && !hasErrorTool               │
     │      && !isEmbeddedShellFocused     │
     │      && !isUserInitiated            │
     └────────────────────────────────────┘

3.2 Principais Arquivos de Código-Fonte

3.3 Decisões de Design

1. Verboso é o padrão. Os usuários veem toda a saída das ferramentas e pensamentos por padrão.
2. Preferência persistente. compactMode é salvo em settings.json e sobrevive entre sessões.
3. Renderização em nível de componente. Cada componente lê compactMode do contexto e ajusta sua própria renderização.
4. Proteção de força de expansão. Quatro condições substituem o modo compacto para garantir que elementos críticos da UI estejam sempre visíveis (confirmações, erros, shell, iniciado pelo usuário).
5. Sem congelamento de snapshot. A alternância sempre mostra saída ao vivo — sem snapshots congelados.
6. Sincronização com diálogo de configurações. Alternar o modo compacto a partir das Configurações atualiza o estado React imediatamente via setCompactMode.
7. Descoberta não intrusiva. O modo compacto é introduzido através da rotação de dicas iniciais em vez de um indicador persistente no rodapé, evitando poluição visual.

3.4 Fluxo do Usuário

Início da sessão → modo verboso (padrão)
     │
     ├─ Todas as saídas de ferramentas, pensamentos, detalhes visíveis
     │
     ├─ Usuário pressiona Ctrl+O (ou alterna em Configurações)
     │     └─→ compactMode = true, persistido
     │         ├─ Grupos de ferramentas mostram resumo em linha única
     │         ├─ Conteúdo de pensamento/thought oculto
     │         └─ Confirmações, erros, shell ainda expandidos
     │
     ├─ Usuário pressiona Ctrl+O novamente
     │     └─→ compactMode = false, persistido
     │         └─ Todos os detalhes visíveis novamente
     │
     └─ Próxima sessão → mesmo modo da última sessão

4. Principais Diferenças em Detalhes

4.1 Filosofia do Modo Padrão

Análise: O padrão compacto do Claude Code funciona porque sua base de usuários é geralmente composta por desenvolvedores experientes que confiam na ferramenta e não precisam ver cada invocação de ferramenta. O padrão verboso do Qwen Code é apropriado para seu estágio inicial, onde construir confiança do usuário através de transparência é importante.

4.2 Modelo de Persistência

Análise: O Claude Code trata a visualização de detalhes como uma necessidade momentânea — você olha e depois volta. O Qwen Code trata como uma preferência estável — alguns usuários sempre querem detalhes, outros sempre querem compacto. Ambas são válidas; a abordagem do Qwen Code é mais flexível.

4.3 Proteção de Confirmação

Análise: A separação arquitetural do Claude Code (camada de sobreposição) é mais robusta. A abordagem de força de expansão do Qwen Code é eficaz, mas exige que cada novo estado interativo seja explicitamente adicionado à lista de condições.

4.4 Abordagem de Renderização

Análise: A abordagem em nível de componente do Qwen Code é mais flexível (por exemplo, força de expansão para condições específicas), mas exige mais disciplina para manter a consistência. A abordagem em nível de tela do Claude Code é mais simples e garante comportamento consistente.

5. Recomendações de Otimização

5.1 [P0] Manter Verboso como Padrão — Nenhuma Alteração Necessária

O padrão verboso do Qwen Code é a escolha certa para seu estágio atual. Usuários novos na ferramenta precisam de transparência para construir confiança. Conforme o produto amadurecer, considere tornar o compacto o padrão (como o Claude Code).

5.2 [P1] Expansão por Ferramenta para Saídas Grandes

O Claude Code mostra “(ctrl+o to expand)” em ferramentas individuais que produzem saída grande. O Qwen Code atualmente só tem uma alternância global. Considere:

• Quando uma única ferramenta produz saída excedendo N linhas, mostrar uma dica “expandir” por ferramenta no modo compacto.
• Escopo: melhoria futura, não prioridade atual.

5.3 [P2] Considerar Substituição com Escopo de Sessão

Alguns usuários podem querer o modo compacto como padrão, mas ocasionalmente precisar do verboso para uma sessão específica. Considere suportar ambos:

• settings.json → padrão persistente (comportamento atual)
• Ctrl+O durante a sessão → substituição temporária apenas para a sessão atual (comportamento do Claude Code)
• Ao reiniciar a sessão → reverter para o valor de settings.json

Isso dá aos usuários o melhor dos dois mundos. A implementação exigiria separar o estado de “padrão das configurações” do estado de “substituição da sessão”.

5.4 [P2] Separação Estrutural para Confirmações

Atualmente, a proteção de confirmação depende das condições de showCompact em ToolGroupMessage. Considere uma abordagem mais robusta:

• Renderizar confirmações em uma camada separada (como a abordagem de sobreposição do Claude Code).
• Isso tornaria arquiteturalmente impossível para o modo compacto afetar confirmações.
• Prioridade menor, já que a abordagem atual de força de expansão funciona corretamente.

6. Situação Atual da Implementação

Após as alterações da branch feat/compact-mode-optimization:

7. Referência de Arquivos

Qwen Code

Claude Code (Referência)