SiYuan Note CLI Skill

Compétence CLI SiYuan Note

Présentation

SiYuan Note propose un CLI (siyuan) pour gérer les espaces de travail, carnets, documents, blocs, et plus encore. Le binaire doit être accessible dans le PATH (vérifiez avec siyuan --version).

Version CLI : v3.8.9. Les commandes ci-dessous reflètent cette version.

Remarque : Si siyuan n'est pas trouvé dans le PATH, essayez SiYuan-Kernel comme nom de commande alternatif.

Workflow

Suivez cette séquence pour chaque requête utilisateur :

1. Découvrir les espaces de travail disponibles

Exécutez siyuan workspace list (pas besoin de drapeau -w) pour obtenir la liste des espaces de travail enregistrés. Si l'utilisateur n'a pas spécifié d'espace de travail, présentez la liste et demandez-lui de choisir.

siyuan workspace list
siyuan workspace info          # afficher l'espace de travail par défaut actuel

2. Verrouiller le chemin de l'espace de travail

Une fois que l'utilisateur a sélectionné un espace de travail (ou fourni un chemin directement), stockez le chemin de l'espace de travail et utilisez-le comme argument -w pour toutes les commandes suivantes (sauf les sous-commandes workspace).

3. Exécuter la commande demandée

Construisez et exécutez la commande cible en ajoutant -w <chemin-espace-travail> (sauf pour la sous-commande workspace). Utilisez -f json pour une sortie exploitable par programme lors de l'analyse des résultats.

Si une commande échoue, vérifiez : (1) le chemin de l'espace de travail est valide, (2) les drapeaux requis comme --id sont fournis, (3) la sous-commande existe dans la version installée du CLI.

Structures courantes

Obtention des IDs de blocs/documents

De nombreuses commandes nécessitent un ID de bloc ou de document (--id). Obtenez les IDs via :

• siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <chemin> -f json — liste les IDs de documents
• siyuan document list --notebook <id> -w <chemin> -f json — liste les documents dans un carnet
• siyuan search <mot-clé> -w <chemin> -f json — recherche et obtient les IDs des résultats

Opérations destructrices — Vérifier, Prévisualiser, Confirmer

Considérez comme opérations destructrices : la suppression/nettoyage (remove, delete, clean, clear, purge), le rollback (history rollback, repo checkout, repo file rollback), et les opérations de remplacement/écrasement (par ex. import data, écrasement d'un fichier existant avec file write, ou commandes de modèle avec --overwrite).

1. Vérifiez l'espace de travail, les IDs/chemins cibles et la portée affectée à l'aide de commandes en lecture seule. Vérifiez si les documents enfants, les données connexes ou le contenu existant seront également affectés ; ne déduisez pas la portée du seul nom de la commande.
2. Exécutez la commande prévue avec --dry-run d'abord et inspectez sa sortie :

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

   Un dry-run réussi n'est pas une approbation de l'utilisateur ni une preuve que toutes les données affectées ont été listées. S'il ne fait que valider les arguments ou donne un aperçu générique, utilisez une inspection en lecture seule pour établir la portée. Si le dry-run échoue ou que les effets ne peuvent pas être établis, arrêtez-vous et expliquez la limitation ; ne réessayez pas sans --dry-run pour le contourner.
3. Si l'autorisation de l'utilisateur ou la portée affectée n'est pas claire, ou si l'aperçu révèle des effets au-delà de la demande, résumez l'espace de travail, les cibles et les conséquences, et demandez une confirmation explicite avant de continuer. Ne devinez pas les cibles et n'étendez pas silencieusement la portée.
4. Une fois la portée vérifiée et autorisée, créez un instantané de récupération dans l'espace de travail cible avant d'exécuter l'opération destructrice :

   siyuan repo create --memo "Avant <brève description de l'opération destructrice>" -w <chemin>
   

   Vérifiez que la création de l'instantané a réussi. Si elle échoue, arrêtez-vous et signalez l'erreur ; ne procédez pas à l'opération destructrice. Un instantané de fin de session de l'état modifié ne remplace pas ce point de récupération pré-opération.
5. Exécutez sans --dry-run uniquement lorsque les effets vérifiés correspondent à la demande de l'utilisateur ou à la confirmation explicite, en conservant le même espace de travail, les mêmes cibles et les mêmes options. Si l'un de ceux-ci change, répétez la vérification, l'aperçu et l'instantané pré-opération.

Analyse de sortie JSON

Utilisez -f json pour une analyse exploitable par programme. La structure JSON dépend de la sous-commande : workspace list renvoie un tableau, tandis que workspace info renvoie un objet. Inspectez la structure de sortie de la commande avant de filtrer avec jq ou des outils similaires ; ne supposez pas que chaque résultat est un tableau.

Erreurs de verrouillage d'espace de travail

Si une commande se termine avec le code 24 et signale lock workspace [...] failed, l'espace de travail est déjà utilisé par un autre processus SiYuan (par ex., l'application de bureau). Fermez l'autre processus ou ciblez un espace de travail différent.

Instantané après les opérations d'écriture

Suivez les modifications réelles des données séparément pour chaque espace de travail au cours de la conversation, y compris les modifications partielles laissées par des commandes échouées. La création d'un instantané elle-même ne compte pas comme une nouvelle modification de données nécessitant un autre instantané.

Avant de terminer la tâche ou de mettre fin à la session, résumez les modifications et créez un instantané de données dans chaque espace de travail modifié, en utilisant le chemin de cet espace de travail et son propre résumé des modifications :

siyuan repo create --memo "<bref résumé des modifications dans cet espace de travail>" -w <chemin-espace-travail-modifié>

Le --memo doit décrire de manière concise ce qui a été créé/modifié/supprimé (par ex. "Créé 3 docs dans /Projets, mis à jour README, supprimé les notes obsolètes"). Vérifiez le succès pour chaque espace de travail ; si un instantané échoue, signalez l'espace de travail affecté et l'erreur plutôt que de prétendre qu'il a été enregistré. Ignorez les espaces de travail sans modification de données ; une session en lecture seule ne nécessite aucun instantané.

Ces instantanés préservent l'état après modification. Ils ne remplacent pas les instantanés de récupération pré-opération requis pour les opérations destructrices.

Concepts du domaine

La compréhension de ces concepts spécifiques à SiYuan est essentielle pour une utilisation correcte du CLI :

Bloc — L'unité fondamentale

Tout est un bloc avec un ID unique. Un document est un bloc de document (type d, c'est-à-dire NodeDocument) qui sert de racine ; les blocs de contenu (titres, paragraphes, listes, code, tableaux) forment un arbre en dessous.

Blocs conteneurs (peuvent contenir des blocs enfants, valides en tant que --parent) : document, blockquote, list, list-item, super-block, callout, tabs, tab-item. Blocs feuilles (ne peuvent pas contenir d'enfants, invalides en tant que --parent) : heading, paragraph, code-block, math-block, table, HTML-block, thematic-break, video, audio, widget, iframe, attribute-view, block-query-embed.

tabs/tab-item sont les types de blocs introduits pour les conteneurs à onglets ; ils apparaissent dans la liste des filtres de type search -t sous les noms tabs et tabItem.

Hiérarchie des titres — Utilisez --previous, pas --parent

Les titres (h1-h6) sont des blocs feuilles. Les blocs qui apparaissent « sous » un titre dans l'interface sont ses frères suivants dans l'AST, pas ses enfants. Pour insérer un bloc en dessous d'un titre, passez l'ID du titre (ou l'ID du dernier bloc actuellement en dessous) comme --previous, pas comme --parent :

siyuan block insert --parent <docID> --previous <headingID> --data "texte" -w <chemin>

Listes imbriquées — list-item ne peut pas contenir directement list-item

Un list-item ne peut pas contenir directement un autre list-item. Pour imbriquer des listes, créez une liste (NodeList) comme enfant du list-item externe, puis ajoutez des list-items à cette liste interne. Le parent d'un list-item doit toujours être une liste.

hPath — Chemin lisible par l'humain

Un hPath est le chemin basé sur le titre affiché dans l'arborescence des documents (par ex. /Diary/2024/June). Renommer un document change son hPath mais pas son ID.

• document list et document move : --hpath accepte un chemin basé sur le titre ; --path accepte un chemin interne basé sur l'ID (par défaut : /). Ces drapeaux ne sont pas interchangeables.
• document create : --path spécifie le chemin du document parent (par défaut : /) ; cette commande ne fournit pas --hpath. Vérifiez siyuan document create --help pour la version installée plutôt que de supposer qu'elle partage les drapeaux de chemin de list/move.

block update — Remplacer, pas ajouter

block update remplace UN bloc entier par un nouveau contenu markdown. Il ne crée ni n'ajoute de nouveaux blocs. Pour à la fois modifier le contenu existant et ajouter du nouveau contenu, appelez block update d'abord, puis block append/prepend/insert comme appels séparés. Passez --lock-type pour rejeter la mise à jour lorsque le type de bloc analysé du nouveau contenu diffère du type du bloc existant.

document move vs block move

document move déplace un document entier (et tous ses enfants) vers le carnet et le chemin parent cibles, en utilisant --hpath pour un chemin basé sur le titre ou --path pour un chemin interne. block move repositionne un seul bloc de contenu sous un nouveau bloc parent.

Note quotidienne — Quand utiliser dailynote vs document

Une note quotidienne est un document spécial situé sur le chemin d'enregistrement des notes quotidiennes du carnet. Pour les demandes de journal/diary/note quotidienne, utilisez dailynote create (pas document create) pour ouvrir la note du jour, puis dailynote append/prepend pour ajouter du contenu.

Icône de carnet vs Icône de document

attr set change l'icône d'un bloc de document — il ne peut pas définir l'icône d'un carnet. Pour les carnets, utilisez notebook set-icon (emoji spécifique) ou notebook random-icon (emoji aléatoire).

Drapeaux globaux

Ces drapeaux sont disponibles sur chaque sous-commande :

Drapeau	Description
-w, --workspace <chemin>	Chemin de l'espace de travail (obligatoire pour toutes les commandes sauf workspace ; facultatif pour serve, qui utilise par défaut l'espace de travail par défaut).
`-f, --format <table	json>`
-v, --log-level <chaîne>	Niveau de journalisation : off, trace, debug, info, warn, error, fatal (par défaut conf.json system.logLevel)
--dry-run	Valide et affiche ce qui se passerait sans faire de modifications
--home-dir <chemin>	Répertoire de base pour la configuration utilisateur (par défaut, le répertoire personnel système)

Remarque : Tous les drapeaux sauf -w (ou --workspace) sont facultatifs. Le CLI utilisera les valeurs par défaut si les drapeaux facultatifs ne sont pas spécifiés.

Référence des sous-commandes

Pour les drapeaux détaillés et les exemples de chaque commande, chargez references/commands.md.

Commande	Sous-commandes
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>"	(direct)
siyuan search <requête>	(direct, avec drapeaux)
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	(direct, avec drapeaux)
siyuan completion	bash, fish, powershell, zsh

Remarque : serve accepte tous les drapeaux globaux plus ses propres drapeaux (--accessAuthCode, --attach-ui, --enable-pprof, --lang, --mode, --port, --readonly, --ssl, --safe-mode, --wd). Il ne nécessite pas -w ; voir references/commands.md pour la liste complète des drapeaux.