SiYuan Note CLI Skill

Habilidade CLI do SiYuan Note

Visão Geral

O SiYuan Note fornece uma CLI (siyuan) para gerenciar workspaces, notebooks, documentos, blocos e muito mais. O binário deve estar disponível no PATH (verifique com siyuan --version).

Versão da CLI: v3.8.9. Os comandos mostrados abaixo refletem esta versão.

Nota: Se siyuan não for encontrado no PATH, tente SiYuan-Kernel como nome de comando alternativo.

Fluxo de Trabalho

Siga esta sequência para cada solicitação do usuário:

1. Descobrir Workspaces Disponíveis

Execute siyuan workspace list (nenhuma flag -w necessária) para obter a lista de workspaces registrados. Se o usuário não especificou um workspace, apresente a lista e peça para ele escolher.

siyuan workspace list
siyuan workspace info          # mostra o workspace padrão atual

2. Fixar o Caminho do Workspace

Após o usuário selecionar um workspace (ou fornecer um caminho diretamente), armazene o caminho do workspace e use-o como argumento -w para todos os comandos subsequentes (exceto subcomandos workspace).

3. Executar o Comando Solicitado

Construa e execute o comando alvo com -w <caminho-do-workspace> anexado (exceto subcomando workspace). Use -f json para saída programática ao analisar resultados.

Se um comando falhar, verifique: (1) o caminho do workspace é válido, (2) flags obrigatórias como --id foram fornecidas, (3) o subcomando existe na versão da CLI instalada.

Padrões Comuns

Obtendo IDs de Bloco/Documento

Muitos comandos exigem um ID de bloco ou documento (--id). Obtenha IDs via:

• siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <caminho> -f json — lista IDs de documentos
• siyuan document list --notebook <id> -w <caminho> -f json — lista documentos em um notebook
• siyuan search <palavra-chave> -w <caminho> -f json — pesquisa e obtém IDs dos resultados

Operações Destrutivas — Verificar, Visualizar, Confirmar

Trate operações de exclusão/limpeza (remove, delete, clean, clear, purge), rollback (history rollback, repo checkout, repo file rollback) e substituição/sobrescrita (ex.: import data, sobrescrever um arquivo existente com file write, ou comandos de template com --overwrite) como operações destrutivas.

1. Verifique o workspace, IDs/caminhos alvo e escopo afetado usando comandos somente leitura. Verifique se documentos filhos, dados relacionados ou conteúdo existente também serão afetados; não infira o escopo apenas pelo nome do comando.
2. Execute o comando pretendido com --dry-run primeiro e inspecione sua saída:

   siyuan notebook remove --id <id> --dry-run -w <caminho>
   

   Um dry-run bem-sucedido não é aprovação do usuário nem prova de que todos os dados afetados foram listados. Se ele apenas validar argumentos ou fornecer uma visualização genérica, use inspeção somente leitura para estabelecer o escopo. Se o dry-run falhar ou os efeitos não puderem ser estabelecidos, pare e explique a limitação; não tente novamente sem --dry-run para contorná-la.
3. Se a autorização do usuário ou o escopo afetado não estiver claro, ou a visualização revelar efeitos além da solicitação, resuma o workspace, alvos e consequências e peça confirmação explícita antes de prosseguir. Não adivinhe alvos nem expanda silenciosamente o escopo.
4. Uma vez que o escopo seja verificado e autorizado, crie um snapshot de recuperação no workspace alvo antes de executar a operação destrutiva:

   siyuan repo create --memo "Antes de <breve descrição da operação destrutiva>" -w <caminho>
   

   Verifique se a criação do snapshot foi bem-sucedida. Se falhar, pare e relate o erro; não prossiga com a operação destrutiva. Um snapshot do estado modificado no final da sessão não substitui este ponto de recuperação pré-operação.
5. Execute sem --dry-run somente quando os efeitos verificados corresponderem à solicitação do usuário ou à confirmação explícita, mantendo o mesmo workspace, alvos e opções. Se algum destes mudar, repita a verificação, visualização e o snapshot pré-operação.

Análise de Saída JSON

Use -f json para análise programática. A estrutura JSON depende do subcomando: workspace list retorna um array, enquanto workspace info retorna um objeto. Inspecione a estrutura de saída do comando antes de filtrar com jq ou ferramentas similares; não presuma que todo resultado é um array.

Erros de Bloqueio de Workspace

Se um comando sair com o código 24 e relatar lock workspace [...] failed, o workspace já está em uso por outro processo do SiYuan (ex.: o aplicativo desktop). Feche o outro processo ou opte por um workspace diferente.

Snapshot Após Operações de Escrita

Rastreie mudanças reais de dados separadamente para cada workspace durante a conversa, incluindo mudanças parciais deixadas por comandos com falha. A criação do snapshot em si não conta como uma nova mudança de dados que exija outro snapshot.

Antes de finalizar a tarefa ou encerrar a sessão, resuma as mudanças e crie um snapshot de dados em cada workspace modificado, usando o caminho desse workspace e seu próprio resumo de mudanças:

siyuan repo create --memo "<breve resumo das mudanças neste workspace>" -w <caminho-do-workspace-modificado>

O --memo deve descrever concisamente o que foi criado/modificado/excluído (ex.: "Criados 3 docs em /Projects, README atualizado, notas obsoletas removidas"). Verifique o sucesso para cada workspace; se um snapshot falhar, relate o workspace afetado e o erro em vez de afirmar que foi salvo. Pule workspaces sem mudanças de dados; uma sessão somente leitura não requer snapshots.

Estes snapshots preservam o estado pós-mudança. Eles não substituem os snapshots de recuperação pré-operação exigidos para operações destrutivas.

Conceitos do Domínio

Entender estes conceitos específicos do SiYuan é essencial para o uso correto da CLI:

Bloco — A Unidade Fundamental

Tudo é um bloco com um ID único. Um documento é um bloco de documento (tipo d, i.e. NodeDocument) que serve como raiz; blocos de conteúdo (cabeçalhos, parágrafos, listas, código, tabelas) formam uma árvore abaixo dele.

Blocos contêiner (podem conter blocos filhos, válidos como --parent): documento, blockquote, lista, list-item, super-bloco, callout, tabs, tab-item. Blocos folha (não podem conter filhos, inválidos como --parent): cabeçalho, parágrafo, code-block, math-block, tabela, HTML-block, thematic-break, vídeo, áudio, widget, iframe, attribute-view, block-query-embed.

tabs/tab-item são os tipos de bloco introduzidos para contêineres em abas; eles aparecem na lista de filtros de tipo search -t como tabs e tabItem.

Hierarquia de Cabeçalhos — Use --previous, Não --parent

Cabeçalhos (h1-h6) são blocos folha. Blocos que aparecem "sob" um cabeçalho na interface são seus irmãos seguintes na AST, não seus filhos. Para inserir um bloco abaixo de um cabeçalho, passe o ID do cabeçalho (ou o ID do último bloco atualmente abaixo dele) como --previous, não como --parent:

siyuan block insert --parent <docID> --previous <headingID> --data "texto" -w <caminho>

Listas Aninhadas — list-item Não Pode Conter Diretamente Outro list-item

Um list-item não pode conter diretamente outro list-item. Para aninhar listas, crie uma lista (NodeList) como filho do list-item externo e, em seguida, adicione list-items a essa lista interna. O pai de um list-item deve ser sempre uma lista.

hPath — Caminho Legível por Humanos

Um hPath é o caminho baseado em título mostrado na árvore de documentos (ex.: /Diário/2024/Junho). Renomear um documento altera seu hPath, mas não seu ID.

• document list e document move: --hpath aceita um caminho baseado em título; --path aceita um caminho baseado em ID interno (padrão: /). Estas flags não são intercambiáveis.
• document create: --path especifica o caminho do documento pai (padrão: /); este comando não fornece --hpath. Verifique siyuan document create --help para a versão instalada, em vez de assumir que compartilha as flags de caminho de list/move.

block update — Substituir, Não Acrescentar

block update substitui o conteúdo inteiro de UM bloco por novo markdown. Ele NÃO cria nem acrescenta novos blocos. Para modificar conteúdo existente e também adicionar novo conteúdo, chame block update primeiro, depois block append/prepend/insert como chamadas separadas. Passe --lock-type para rejeitar a atualização quando o tipo de bloco analisado do novo conteúdo diferir do tipo do bloco existente.

document move vs block move

document move realoca um documento inteiro (e todos os seus filhos) para o notebook e caminho pai alvo, usando --hpath para um caminho baseado em título ou --path para um caminho interno. block move reposiciona um único bloco de conteúdo sob um novo bloco pai.

Nota Diária — Quando Usar dailynote vs document

Uma nota diária é um documento especial no caminho de salvamento de notas diárias do notebook. Para solicitações de diário/jornal/nota diária, use dailynote create (não document create) para abrir a nota de hoje, depois dailynote append/prepend para adicionar conteúdo.

Ícone de Notebook vs Ícone de Documento

attr set altera o ícone de um bloco de documento — ele não pode definir o ícone de um notebook. Para notebooks, use notebook set-icon (emoji específico) ou notebook random-icon (emoji aleatório).

Flags Globais

Estas flags estão disponíveis em todos os subcomandos:

Flag	Descrição
-w, --workspace <caminho>	Caminho do workspace (obrigatório para todos os comandos, exceto workspace; opcional para serve, que usa o workspace padrão).
-f, --format <tabela|json>	Formato de saída (padrão: tabela)
-v, --log-level <string>	Nível de log: off, trace, debug, info, warn, error, fatal (padrão: system.logLevel em conf.json)
--dry-run	Valida e imprime o que aconteceria sem fazer mudanças
--home-dir <caminho>	Diretório base para configuração do usuário (padrão: diretório home do sistema do usuário)

Nota: Todas as flags, exceto -w (ou --workspace), são opcionais. A CLI usará valores padrão se as flags opcionais não forem especificadas.

Referência de Subcomandos

Para flags detalhadas e exemplos de cada comando, carregue references/commands.md.

Comando	Subcomandos
siyuan workspace	list, info
siyuan notebook	list, create, open, close, rename, remove, set-icon, random-icon
siyuan document	list, get/info, create, rename, move, duplicate, remove, search
siyuan block	get, children, insert, append, prepend, update, delete, move, stat, dom, kramdown, breadcrumb, batch-get, batch-kramdown
siyuan sql "<stmt>"	(direto)
siyuan search <consulta>	(direto, com flags)
siyuan export	md, html, docx, sy, md-zip, preview, data
siyuan import	md, sy, data
siyuan dailynote	create, append, prepend
siyuan asset	unused, clean, stat, upload
siyuan attr	get, set, batch-get
siyuan bookmark	list, labels, rename, remove
siyuan tag	list, rename, remove
siyuan history	list, get, search, rollback, clear
siyuan ref	backlinks, mentions, refresh
siyuan repo	list, create, diff, checkout, tag, untag, purge, search, file
siyuan sync	pull, push, status
siyuan database	search, get, keys, render, unused, clean, key, item
siyuan file	list, read, write, copy, rename, delete, find, grep, stat
siyuan inbox	list, get, convert
siyuan outline	get
siyuan template	search, get, create, save-as, render, remove
siyuan system	current-time
siyuan serve	(direto, com flags)
siyuan completion	bash, fish, powershell, zsh

Nota: serve aceita todas as flags globais mais suas próprias flags (--accessAuthCode, --attach-ui, --enable-pprof, --lang, --mode, --port, --readonly, --ssl, --safe-mode, --wd). Não requer -w; veja references/commands.md para a lista completa de flags.