Transformar Escritório

Transforme uma seleção estrutural de um documento do Office/PDF em um novo arquivo derivado.

Duas invariantes se aplicam a cada operação:

1. O arquivo de origem é somente leitura. Cada resultado é um novo arquivo; ambos os scripts se recusam a escrever no caminho de origem ou a sobrescrever um arquivo existente. Nunca contorne isso com edições ad-hoc no shell no original.
2. Âncoras são estruturais. As seleções se referem às próprias coordenadas do documento — planilha + intervalo A1, número ordinal de parágrafo no nível do corpo, número de página baseado em um — nunca posições de tela ou DOM.

Quando usar qual ferramenta

• Precisa apenas ler um documento para resumir ou responder a perguntas → use mcp__cherry-tools__to_markdown em vez disso (veja a habilidade cherry-tool-guide); é com perdas, mas feito para leitura.
• O usuário quer um arquivo como resultado — um intervalo extraído, um fragmento convertido, uma cópia editada → esta habilidade.

Entrada: referências de seleção

As superfícies de chat podem fornecer um bloco selection-ref delimitado:

{"path": "/abs/report.xlsx", "anchor": {"format": "xlsx", "sheet": "Sheet1", "range": "A1:C10"}, "excerpt": "…", "fileStamp": {"size": 1024, "mtimeMs": 1700000000000}}

O objeto anchor é exatamente o que os scripts recebem via --anchor.

Verificação de atualidade. fileStamp.mtimeMs são milissegundos desde a época Unix, arredondados para milissegundos inteiros. Não o compare com a saída padrão de stat: stat -f %m (macOS) e stat -c %Y (GNU) fornecem segundos inteiros, então multiplicar por 1000 perde a parte sub-segundo e nunca corresponde. Leia milissegundos inteiros da maneira como o aplicativo os escreveu:

uv run python -c "import os,sys;st=os.stat(sys.argv[1]);print(st.st_size, st.st_mtime_ns//1_000_000)" '/abs/report.xlsx'

Trate o arquivo como alterado quando o tamanho diferir, ou quando os mtimes diferirem em mais de 2 ms. A tolerância é pequena de propósito: ambos os lados arredondam o mesmo timestamp de nanossegundo para milissegundos, então eles concordam exatamente, e os poucos milissegundos cobrem apenas o arredondamento de um double que não pode mais representar os milissegundos da época atual exatamente. Uma janela mais ampla esconderia edições reais — uma mudança de mesmo tamanho feita dentro dela seria lida como inalterada, o que é por que a verificação de âncora abaixo não é opcional. Em caso de alteração, informe ao usuário que o arquivo mudou desde que ele selecionou e peça para re-selecionar — nunca re-ancore silenciosamente.

Verificação de âncora. Antes de uma edição de cópia de patch, verifique também se a âncora ainda aponta para onde o usuário pensa: extraia a região ancorada e compare seu texto com o excerpt de referência, normalizando ambos os lados da mesma maneira (NFC, colapse cada sequência de espaço em branco para um único espaço, recorte). Os dois não são iguais e não têm a intenção de ser — o excerpt é o que o usuário selecionou, enquanto a extração é a região inteira que uma edição substituiria. Uma seleção dentro de uma região faz com que o excerpt seja o lado mais curto; uma seleção que ultrapassa essa região ancora onde ela começa, o que a torna a mais longa. Portanto, o teste é contenção, de qualquer forma que se ajuste: o excerpt aparece dentro da extração, ou a cauda da extração é onde o excerpt começa. Somente quando nenhum dos dois se aplica, a âncora parou de apontar para a seleção — então pare e diga ao usuário, nunca edite em uma âncora incompatível e nunca procure por uma localização "boa o suficiente". Dois casos precisam de cuidado porque os dois lados não são diretamente comparáveis como estão:

• xlsx: o excerpt são células separadas por tabulação e linhas separadas por nova linha, enquanto a extração escreve csv ou md. Compare os valores das células, não o arquivo bruto — leia o csv com um leitor de csv e junte os campos com espaços únicos antes de normalizar, para que , e | nunca contem como uma diferença. Essa junção descarta os limites das células em ambos os lados, então uma correspondência prova que o texto está inalterado, não a grade — as mesmas palavras re-divididas entre células ainda são lidas como uma correspondência. A verificação de atualidade acima é o que pega isso; nunca a pule em uma verificação de âncora bem-sucedida. Formatos de número são a segunda assimetria: o excerpt contém o que o Excel exibe, porque é isso que o usuário apontou (1,234.50, 45.67%), enquanto a extração escreve o valor armazenado (1234.5, 0.4567). Nenhum dos lados está errado, então uma célula formatada nunca corresponde literalmente. Compare essas células por valor e deixe-as de fora das strings unidas para que o teste de contenção seja executado apenas nas células de texto. Datas, horas e durações são a mesma assimetria vista do outro lado: a extração escreve uma forma fixa (2024-01-03,

…