officecli/officecli-skills

OfficeCLI

Visão Geral

officecli é o CLI de código fechado do OfficeCLI para manipulação de documentos do Office. Ele pode suportar fluxos de trabalho de geração, modificação e conversão de formato entre pptx, docx e xlsx. Portanto, esta skill deve primeiro direcionar tarefas de arquivos do Office para uma verificação de capacidade do officecli antes de decidir como executá-las.

Quando Usar Esta Skill

Use esta skill quando a tarefa envolver:

• criar uma apresentação, deck de relatório, proposta, folheto ou briefing em pptx
• criar um documento escrito, memorando, rascunho ou relatório em docx
• criar uma planilha, entrega baseada em tabela ou planilha estruturada em xlsx
• modificar um arquivo PowerPoint, Word ou Excel existente
• converter documentos do Office para outro formato de saída, como markdown, csv, pdf ou um formato diferente do Office
• decidir se um fluxo de trabalho de arquivos do Office solicitado é algo que o officecli pode manipular diretamente

Não use esta skill para perguntas e respostas puras, brainstorming superficial sem saída de arquivo ou orientação de manutenção de código-fonte.

Comportamento Principal do Produto

• officecli suporta fluxos de geração pptx, docx e xlsx
• pptx habilita imagens geradas automaticamente por padrão quando o conteúdo e o layout são adequados
• --no-images desabilita a geração de imagens para pptx
• ao usar agent-bridge, os agentes devem tratar capabilities/get -> document_generation.pptx.image_support como o contrato legível por máquina autoritativo para o comportamento de imagem PPT
• ao usar agent-bridge, os agentes devem tratar capabilities/get -> update como o contrato legível por máquina autoritativo para disponibilidade de atualização binária
• se a geração de imagens falhar para um slide, o PPT ainda deve ser gerado com esse slide rebaixado para uma versão sem imagem
• instalar a skill pública também pode tentar instalar o binário officecli quando ele estiver ausente
• para integrações orientadas a agentes, officecli agent-bridge agora expõe um protocolo estruturado JSON-RPC 2.0 sobre stdio
• a configuração persistente é tratada através de officecli config ..., não através de um assistente init

Verificação de Capacidade

Quando uma tarefa envolve manipulação de documentos do Office, primeiro verifique se a superfície atual do officecli parece suportar esse fluxo de trabalho.

• antes de cada tarefa do Office, execute fix-officecli-env.sh uma vez para que o agente atualize o pacote de skill local e repare qualquer configuração ausente do officecli
• verifique se officecli está disponível antes de decidir sobre o caminho final do artefato
• após a etapa de reparo, execute check-officecli-env.sh para detectar se o officecli está ausente, mal configurado ou já pronto
• trate o código de saída 0 como pronto, 10 como reparável e 20 como bloqueado
• inspecione primeiro a superfície visível do CLI, como officecli --help ou a ajuda de subcomando relevante, antes de assumir suporte
• use a saída de ajuda e a descrição pública do produto para julgar se o fluxo de trabalho de criar, modificar ou converter solicitado é realmente suportado
• se o suporte não for claro, diga isso claramente em vez de fingir que a capacidade existe
• se a atualização ou verificação falhar, pare e relate o erro de ambiente do officecli; não mude para outro caminho de geração local do Office por conta própria

Reparo de Ambiente

Execute fix-officecli-env.sh em cada tarefa, não apenas quando o ambiente parecer quebrado.

• o script de correção deve primeiro atualizar o pacote de skill local do Codex
• o script de correção deve instalar officecli quando ele estiver ausente, mas não deve atualizar um binário existente a menos que o host opte explicitamente, por exemplo, com OFFICECLI_REFRESH_BINARY=1
• quando o usuário pedir explicitamente para desinstalar officecli, execute uninstall-officecli.sh
• se officecli estiver ausente, o script de correção deve instalá-lo automaticamente através do instalador público de distribuição
• se a configuração de geração ou licença estiver ausente, pergunte apenas pelos valores ausentes e deixe o script de correção chamar os comandos officecli config ... relevantes
• a configuração de publicação é necessária por padrão, para que os arquivos gerados retornem URLs de visualização online
• se o usuário quiser saída apenas local, defina OFFICECLI_SKIP_PUBLISH_SETUP=1 antes de executar o script de correção
• após o reparo, execute novamente check-officecli-env.sh e prossiga somente quando ele retornar como pronto
• quando o reparo falhar, exiba o status estruturado final do script de correção em vez de misturá-lo com uma verificação de prontidão posterior
• se o reparo ainda falhar, exiba os itens ausentes claramente em vez de mudar silenciosamente para outro caminho de artefato

Preferência de Execução

Se a verificação de capacidade indicar que o officecli suporta o fluxo de trabalho de arquivos do Office solicitado, prefira officecli como caminho de execução para o artefato final.

• não ignore silenciosamente o officecli com outro caminho local de geração ou conversão de arquivos do Office quando o officecli parecer suportar a tarefa
• se o officecli estiver indisponível ou falhar, diga isso claramente em vez de mudar silenciosamente o caminho do artefato final
• não use Node, Python, LibreOffice, pptxgenjs ou scripts personalizados para gerar o arquivo final do Office, a menos que o usuário aprove explicitamente sair do caminho do officecli
• se a verificação de capacidade sugerir que o officecli não suporta o fluxo de trabalho, ou o usuário aceitar explicitamente um caminho alternativo após isso, o agente pode prosseguir com essa alternativa

Para clientes agente, prefira a bridge estruturada em vez da superfície CLI orientada a humanos.

• a primeira escolha para integração de agente é officecli agent-bridge
• não analise a saída de spinner ou linhas de progresso humano como um protocolo quando agent-bridge estiver disponível
• chame initialize ou capabilities/get primeiro e armazene em cache os campos de capacidade de imagem PPT retornados antes de invocar a geração
• também armazene em cache capabilities/get -> update; se available=true, prefira exibir update_command ou acionar seu próprio fluxo de atualização em vez de analisar prompts humanos do CLI
• use task/invoke para solicitações de geração e consuma notificações event para estado intermediário
• use task/respond para perguntas de acompanhamento em vez de escrever respostas de forma livre para prompts brutos do stdin
• use task/cancel para cancelamento e task/status como fallback de polling

Limite de Ferramentas

Python ou outras ferramentas ainda podem ser usadas para trabalho de suporte em torno de arquivos do Office.

• inspeção, validação, depuração, análise XML ou zip e diff de artefatos são usos de suporte aceitáveis
• essas ferramentas não devem substituir silenciosamente o officecli para o caminho final do artefato do Office quando o officecli parecer suportar o fluxo de trabalho solicitado
• a regra é sobre roteamento e manipulação final de artefatos, não sobre banir uma linguagem ou ferramenta específica para trabalho de análise

Orientação de Prompt

Ao pedir a um agente para usar officecli, inclua os detalhes que mais afetam a qualidade da saída:

• o tópico ou assunto do arquivo
• se a tarefa é criar, modificar ou converter
• o público-alvo
• o tom ou estilo desejado
• expectativas de página, seção ou contagem de slides
• se imagens devem ser usadas, evitadas ou deixadas para o comportamento padrão
• o arquivo de origem e o formato de destino quando a tarefa for uma conversão
• quaisquer restrições importantes, como linguagem concisa, estilo executivo ou estrutura pesada de tabelas

Quando a tarefa for sobre configurar ou corrigir o officecli, prefira os comandos de configuração explícitos:

• ./check-officecli-env.sh
• ./fix-officecli-env.sh
• ./uninstall-officecli.sh
• officecli config status
• officecli config set-generation
• officecli config set-license
• officecli config set-publish
• officecli config set-defaults

Expectativas de Saída

Uma boa solicitação officecli deve levar a um artefato de arquivo finalizado, não apenas a conteúdo sugerido. A skill deve primeiro determinar se o officecli suporta o fluxo de trabalho de arquivos do Office solicitado, depois preferir o officecli para o artefato final quando esse suporte estiver disponível.

Não execute a pontuação PPT automaticamente após a geração, a menos que o usuário peça explicitamente por pontuação, revisão, validação ou verificação de qualidade.

• o comportamento padrão após a geração é a entrega do artefato de arquivo
• caminho de pontuação opcional é officecli score ... ou office.review / office.score

Notas do Protocolo do Agente

Quando o chamador é um agente ou cliente TUI, a superfície de protocolo preferida é:

• transporte: stdio
• enquadramento: cabeçalhos Content-Length
• plano de controle: JSON-RPC 2.0
• nome da ferramenta: office.generate

Conjunto mínimo de métodos:

• initialize
• capabilities/get
• session/open
• session/close
• task/invoke
• task/respond
• task/status
• task/cancel

Tipos de eventos importantes:

• task.started
• task.progress
• task.question
• task.output
• task.completed
• task.failed
• task.cancelled

Ao gerar orientação ou exemplos para outro agente, prefira mostrar o caminho do protocolo agent-bridge primeiro e só recorra a officecli new ... quando o usuário quiser claramente a interface humana do CLI.

Para todos os clientes de agente, use as seguintes regras de manipulação de imagem:

• leia capabilities/get -> document_generation.pptx.image_support
• leia capabilities/get -> update
• assuma o comportamento de imagem padrão do pptx de default_enabled, não de suposições codificadas do cliente
• nunca analise prompts humanos de atualização da saída padrão do officecli quando agent-bridge estiver disponível; use campos estruturados de update
• se o usuário quiser explicitamente um PPT somente texto, passe enable_images=false e mencione disable_flag quando útil
• se o usuário perguntar por que um PPT gerado não tem imagens, aponte para config_command
• se task.output, task.completed ou task/status contiver result_meta.image_support.attention_required=true, exiba isso como um problema de primeira classe em vez de enterrá-lo em avisos brutos
• quando result_meta.image_support.reason=image_generation_degraded, diga explicitamente ao usuário para verificar image_base_url, image_api_key e image_model
• mantenha warnings para exibição, mas prefira result_meta para decisões de máquina

Empacotamento OpenClaw

Este repositório também fornece um pacote voltado para OpenClaw em skills/openclaw-officecli/.

• use esse pacote para usuários do OpenClaw em vez de reutilizar diretamente o diretório de skill orientado ao Codex
• o pacote OpenClaw assume implantação local no mesmo host com officecli agent-bridge
• o fluxo de instalação do OpenClaw está documentado em docs/openclaw-user-quickstart.md