Notas no Canvas

Um cartão de nota é texto em Markdown guardado num arquivo .md. Serve para duas coisas ao mesmo tempo: é a sua memória do projeto no quadro, e é o material que os agentes podem ler e escrever.

Porque é um arquivo de verdade, a nota sobrevive ao app: fechar e reabrir não perde texto, e qualquer ferramenta de fora do Elyra pode ler o mesmo arquivo.

Onde os arquivos ficam

As notas não moram dentro do projeto. Elas ficam numa pasta gerenciada pelo app, fora do repositório, com um caminho por workspace no formato:

~/.elyra/projetos/<projeto>/<workspace>/notas/

Os nomes das pastas de projeto e de workspace carregam um sufixo identificador, então o caminho exato não é previsível de cabeça. O caminho absoluto real é o que a linha de comando devolve no campo noteFilePath ao listar ou ler uma nota — use esse valor quando precisar do arquivo no disco.

Essa decisão tem um motivo prático: quando as notas ficavam dentro do repositório, uma limpeza de arquivos não versionados (git clean -xdf) levava as notas junto. Fora do projeto, isso não acontece.

Duas consequências:

• Workspace remoto por SSH é a exceção. Nesse caso a pasta de notas fica dentro do checkout, no host remoto. Isso é declarado como temporário, até existir resolução de pasta pessoal remota — não conte com paridade entre local e SSH para notas.
• O identificador guardado da nota não é um endereço. O cartão guarda uma identidade no formato .elyra/notas/<nome>.md, que não é onde o arquivo está de fato. Só o noteFilePath é o caminho real.

Notas antigas. As notas que ficavam dentro do projeto, nas duas pastas antigas, são movidas para a pasta gerenciada. A migração roda na inicialização, não sobrescreve um arquivo já existente no destino (um nome ocupado ganha um sufixo) e, se falhar, deixa o arquivo onde está para tentar de novo na próxima inicialização. Ela é best-effort: um arquivo pode ficar para trás numa falha.

Criar uma nota

Pela barra do topo: Adicionar Nota › Nota. Pelo clique direito no fundo: “Adicionar aqui” › Nota. Os dois criam o cartão e o arquivo, e o editor da nota recém-criada recebe o foco automaticamente — você pode começar a escrever.

Pela linha de comando, a nota nasce já com conteúdo:

elyra canvas create note --title "Resumo da reunião" --content "Primeira linha"
elyra canvas create note --content-file ./texto.md

• --content escreve o texto no arquivo no nascimento.
• --content-file lê de um arquivo, ou de - para ler da entrada padrão. É o caminho para texto com várias linhas — aspas no shell estragam quebras de linha.
• Com --title, o arquivo nasce com esse nome e o nome fica fixo.
• Sem --title, o nome segue a primeira linha do conteúdo. Enquanto você não digitar um nome, o cartão mostra “automático”; digitar um nome o fixa.

O nome do arquivo é saneado: caracteres inválidos viram -, nomes reservados do sistema ganham prefixo e há um teto de comprimento. Você não precisa cuidar disso.

Editar

O corpo do cartão é um editor rico de Markdown, com barra de ferramentas e um campo de escrita com a dica “Escreva sua nota…”.

• A gravação é adiada em cerca de 600 ms depois da última tecla. É por isso que parar de digitar por um instante e olhar o arquivo no disco é a forma de confirmar que ele foi salvo.
• Edições feitas fora do app aparecem no cartão. O app observa o arquivo e reflete o que mudou.
• Uma falha de leitura bloqueia o editor em vez de esvaziar o arquivo. Se a nota não puder ser lida, o cartão avisa e oferece Tentar novamente — nada foi apagado, e você deve conferir se o arquivo foi movido ou apagado fora do Elyra.
• Fechar durante uma edição pendente descarrega a gravação adiada antes de apagar, para não recriar um arquivo que deveria sair.

Ferramentas da nota

A barra da nota traz negrito, itálico, riscado, lista e lista numerada, além da paleta de cores.

Cor de fundo

A paleta oferece Padrão, Amarelo, Verde, Azul, Rosa, Roxo e Cinza. Escolher Padrão limpa a cor. A cor é uma propriedade do cartão, não do texto: ela não altera o arquivo .md e, portanto, não viaja junto com a nota se você abrir o arquivo em outro lugar.

Buscar dentro da nota

A barra de busca “Buscar na nota” destaca e navega pelos resultados dentro do corpo do cartão, com Anterior, Próximo e um contador no formato atual de total, além de “Nenhum resultado” quando não há correspondência. Esc fecha a busca.

A busca é só de interface e não altera o arquivo nem o processo.

Escrever numa nota pela linha de comando

Um agente pode ler e escrever a nota sem abrir o editor:

elyra canvas note read <note> [--workspace <selector>] [--json]
elyra canvas note write <note> (--content <text> | --content-file <path|->)
                              [--append] [--workspace <selector>] [--json]

• <note> aceita o id do cartão, o título do cartão ou o nome da nota.
• Sem --append, o conteúdo substitui o arquivo inteiro. Com --append, o texto vai para o fim, depois de uma quebra de linha.
• Sem --json, a leitura imprime o conteúdo puro da nota.

Escrita concorrente com o editor. O comando é o escritor mais novo: o texto que ainda estava na gravação adiada do editor é descartado de propósito, e o cartão na tela pega o conteúdo novo pelo observador de arquivo. Antes de escrever numa nota que está aberta, salve o que você digitou.

O app precisa estar aberto. Sem janela do aplicativo, essas operações são recusadas em vez de gravar num estado que ninguém vê.

Limites

• Workspace remoto por SSH. As notas ficam dentro do checkout no host remoto, e a migração para a pasta gerenciada não roda nesse caso. Não há paridade entre local e SSH para notas.
• Uma nota cujo arquivo sumiu não monta editor nem grava. Isso é proposital: evita que o salvamento automático recrie o arquivo vazio por cima do que existia. O cartão mostra o erro, preserva o texto que já conhecia e oferece Tentar novamente.
• Dois cartões com o mesmo nome tornam o seletor ambíguo. A linha de comando pede para você usar o id nesse caso — o nome é conforto, não endereço único.
• Não há um limite de tamanho documentado para a nota. Uma nota grande é lida e gravada inteira; não conte com truncamento nem com aviso de “grande demais”.