Carrot404/siyuan-skill

SiYuan-Notiz-CLI-Skill

Überblick

SiYuan Note stellt eine CLI (siyuan) zur Verfügung, mit der Arbeitsbereiche, Notizbücher, Dokumente, Blöcke und mehr verwaltet werden können. Das Binärprogramm muss im PATH verfügbar sein (überprüfen mit siyuan --version).

CLI-Version: v3.8.9. Die unten aufgeführten Befehle entsprechen dieser Version.

Hinweis: Falls siyuan nicht im PATH gefunden wird, kann als alternativer Befehl SiYuan-Kernel verwendet werden.

Arbeitsablauf

Führe für jede Benutzeranfrage die folgende Reihenfolge aus:

1. Verfügbare Arbeitsbereiche ermitteln

Führe siyuan workspace list (ohne -w-Flag) aus, um eine Liste der registrierten Arbeitsbereiche zu erhalten. Wenn der Benutzer keinen Arbeitsbereich angegeben hat, präsentiere die Liste und bitte ihn, einen auszuwählen.

siyuan workspace list
siyuan workspace info          # zeigt den aktuellen Standard-Arbeitsbereich an

2. Arbeitsbereichspfad festlegen

Nachdem der Benutzer einen Arbeitsbereich ausgewählt (oder direkt einen Pfad angegeben) hat, speichere den Arbeitsbereichspfad und verwende ihn als -w-Argument für alle nachfolgenden Befehle (außer für workspace-Unterbefehle).

3. Angeforderten Befehl ausführen

Erstelle und führe den Zielbefehl mit angehängtem -w <Arbeitsbereichspfad> aus (außer für den workspace-Unterbefehl). Verwende -f json für programmatische Ausgabe, wenn Ergebnisse geparst werden sollen.

Wenn ein Befehl fehlschlägt, überprüfe: (1) ob der Arbeitsbereichspfad gültig ist, (2) ob erforderliche Flags wie --id angegeben wurden, (3) ob der Unterbefehl in der installierten CLI-Version existiert.

Häufige Muster

Block-/Dokument-IDs abrufen

Viele Befehle erfordern eine Block- oder Dokument-ID (--id). IDs erhältst du über:

• siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <pfad> -f json — listet Dokument-IDs auf
• siyuan document list --notebook <id> -w <pfad> -f json — listet Dokumente in einem Notizbuch auf
• siyuan search <Stichwort> -w <pfad> -f json — Suche und ID-Gewinnung aus Ergebnissen

Zerstörerische Operationen – Überprüfen, Vorschau, Bestätigen

Behandle Lösch-/Bereinigungsvorgänge (remove, delete, clean, clear, purge), Rollbacks (history rollback, repo checkout, repo file rollback) sowie Ersetzungs-/Überschreibungsvorgänge (z. B. import data, Überschreiben einer vorhandenen Datei mit file write oder Vorlagenbefehle mit --overwrite) als zerstörerische Operationen.

1. Überprüfe den Arbeitsbereich, die Ziel-IDs/-Pfade und den betroffenen Bereich mit Nur-Lese-Befehlen. Prüfe, ob auch Unterdokumente, zugehörige Daten oder vorhandene Inhalte betroffen sind; leite den Bereich nicht allein aus dem Befehlsnamen ab.
2. Führe den beabsichtigten Befehl zuerst mit --dry-run aus und untersuche seine Ausgabe:

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

   Ein erfolgreicher Dry-Run ist keine Benutzerzustimmung oder ein Beweis dafür, dass alle betroffenen Daten aufgelistet wurden. Wenn er nur Argumente validiert oder eine allgemeine Vorschau liefert, verwende eine Nur-Lese-Inspektion, um den Bereich zu ermitteln. Wenn der Dry-Run fehlschlägt oder die Auswirkungen nicht festgestellt werden können, stoppe und erkläre die Einschränkung; wiederhole den Vorgang nicht ohne --dry-run, um ihn zu umgehen.
3. Wenn die Autorisierung des Benutzers oder der betroffene Bereich unklar ist oder die Vorschau Auswirkungen zeigt, die über die Anfrage hinausgehen, fasse den Arbeitsbereich, die Ziele und die Konsequenzen zusammen und bitte vor dem Fortfahren um explizite Bestätigung. Rate keine Ziele und erweitere den Bereich nicht stillschweigend.
4. Sobald der Bereich überprüft und autorisiert ist, erstelle einen Wiederherstellungs-Snapshot im Ziel-Arbeitsbereich, bevor die zerstörerische Operation ausgeführt wird:

   siyuan repo create --memo "Vor <kurze Beschreibung der zerstörerischen Operation>" -w <pfad>
   

   Überprüfe, ob die Snapshot-Erstellung erfolgreich war. Wenn sie fehlschlägt, stoppe und melde den Fehler; führe die zerstörerische Operation nicht durch. Ein Snapshot des geänderten Zustands am Ende der Sitzung ersetzt diesen Wiederherstellungspunkt vor der Operation nicht.
5. Führe ohne --dry-run nur dann aus, wenn die überprüften Auswirkungen der Benutzeranfrage oder der expliziten Bestätigung entsprechen, und behalte denselben Arbeitsbereich, dieselben Ziele und Optionen bei. Wenn sich eine dieser Angaben ändert, wiederhole die Überprüfung, die Vorschau und den Snapshot vor der Operation.

JSON-Ausgabe parsen

Verwende -f json für die programmatische Analyse. Die JSON-Struktur variiert je nach Unterbefehl: workspace list gibt ein Array zurück, während workspace info ein Objekt zurückgibt. Untersuche die Ausgabestruktur des Befehls, bevor du mit jq oder ähnlichen Tools filterst; nimm nicht an, dass jedes Ergebnis ein Array ist.

Fehler bei Arbeitsbereichssperre

Wenn ein Befehl mit Code 24 endet und lock workspace [...] failed meldet, wird der Arbeitsbereich bereits von einem anderen SiYuan-Prozess (z. B. der Desktop-App) verwendet. Schließe entweder den anderen Prozess oder wähle einen anderen Arbeitsbereich.

Snapshot nach Schreiboperationen

Verfolge tatsächliche Datenänderungen für jeden Arbeitsbereich während des Gesprächs separat, einschließlich partieller Änderungen, die durch fehlgeschlagene Befehle zurückbleiben. Die Snapshot-Erstellung selbst zählt nicht als neue Datenänderung, die einen weiteren Snapshot erfordert.

Bevor du die Aufgabe beendest oder die Sitzung schließt, fasse die Änderungen zusammen und erstelle in jedem geänderten Arbeitsbereich einen Daten-Snapshot, wobei du den Pfad dieses Arbeitsbereichs und seine eigene Änderungszusammenfassung verwendest:

siyuan repo create --memo "<kurze Zusammenfassung der Änderungen in diesem Arbeitsbereich>" -w <pfad-des-geänderten-arbeitsbereichs>

Das --memo sollte prägnant beschreiben, was erstellt/geändert/gelöscht wurde (z. B. "3 Dokumente in /Projekte erstellt, README aktualisiert, veraltete Notizen entfernt"). Überprüfe den Erfolg für jeden Arbeitsbereich; wenn ein Snapshot fehlschlägt, melde den betroffenen Arbeitsbereich und den Fehler, anstatt zu behaupten, er sei gespeichert worden. Überspringe Arbeitsbereiche ohne Datenänderungen; eine Nur-Lese-Sitzung erfordert keine Snapshots.

Diese Snapshots bewahren den Zustand nach den Änderungen. Sie ersetzen nicht die Wiederherstellungs-Snapshots vor der Operation, die für zerstörerische Operationen erforderlich sind.

Domänenkonzepte

Das Verständnis dieser SiYuan-spezifischen Konzepte ist für die korrekte Verwendung der CLI unerlässlich:

Block – Die grundlegende Einheit

Alles ist ein Block mit einer eindeutigen ID. Ein Dokument ist ein Dokumentblock (Typ d, d. h. NodeDocument), der als Wurzel dient; Inhaltsblöcke (Überschriften, Absätze, Listen, Code, Tabellen) bilden einen Baum darunter.

Container-Blöcke (können untergeordnete Blöcke enthalten, gültig als --parent): Dokument, Blockzitat, Liste, Listenelement, Super-Block, Callout, Tabs, Tab-Element. Blatt-Blöcke (können keine untergeordneten Elemente enthalten, ungültig als --parent): Überschrift, Absatz, Code-Block, Mathematik-Block, Tabelle, HTML-Block, Themenwechsel, Video, Audio, Widget, Iframe, Attributansicht, Block-Abfrage-Einbettung.

tabs/tab-item sind die Blocktypen, die für Registerkarten-Container eingeführt wurden; sie erscheinen in der search -t-Typfilterliste als tabs und tabItem.

Überschriftenhierarchie – Verwende --previous, nicht --parent

Überschriften (h1-h6) sind Blatt-Blöcke. Blöcke, die in der Benutzeroberfläche „unter" einer Überschrift erscheinen, sind im AST nachfolgende Geschwister, keine Kinder. Um einen Block unterhalb einer Überschrift einzufügen, übergib die ID der Überschrift (oder die ID des letzten Blocks, der sich derzeit darunter befindet) als --previous, nicht als --parent:

siyuan block insert --parent <docID> --previous <headingID> --data "text" -w <pfad>

Verschachtelte Listen – Listenelement kann nicht direkt Listenelement enthalten

Ein Listenelement kann nicht direkt ein weiteres Listenelement enthalten. Um Listen zu verschachteln, erstelle eine Liste (NodeList) als untergeordnetes Element des äußeren Listenelements und füge dann Listenelemente zu dieser inneren Liste hinzu. Das Elternelement eines Listenelements muss immer eine Liste sein.

hPath – Für Menschen lesbarer Pfad

Ein hPath ist der titelbasierte Pfad, der im Dokumentenbaum angezeigt wird (z. B. /Diary/2024/June). Das Umbenennen eines Dokuments ändert seinen hPath, aber nicht seine ID.

• document list und document move: --hpath akzeptiert einen titelbasierten Pfad; --path akzeptiert einen internen ID-basierten Pfad (Standard: /). Diese Flags sind nicht austauschbar.
• document create: --path gibt den Pfad des übergeordneten Dokuments an (Standard: /); dieser Befehl bietet kein --hpath. Überprüfe siyuan document create --help für die installierte Version, anstatt anzunehmen, dass er die Pfad-Flags von list/move teilt.

block update – Ersetzen, nicht anhängen

block update ersetzt den gesamten Inhalt EINES Blocks durch neues Markdown. Es erstellt oder hängt KEINE neuen Blöcke an. Um sowohl vorhandene Inhalte zu ändern als auch neue Inhalte hinzuzufügen, rufe zuerst block update auf und dann block append/prepend/insert als separate Aufrufe. Übergib --lock-type, um das Update abzulehnen, wenn sich der geparste Blocktyp des neuen Inhalts vom Typ des vorhandenen Blocks unterscheidet.

document move vs. block move

document move verschiebt ein gesamtes Dokument (und alle seine Kinder) in das Ziel-Notizbuch und den übergeordneten Pfad, wobei --hpath für einen titelbasierten Pfad oder --path für einen internen Pfad verwendet wird. block move positioniert einen einzelnen Inhaltsblock unter einem neuen übergeordneten Block.

Tägliche Notiz – Wann dailynote vs. document verwenden

Eine tägliche Notiz ist ein spezielles Dokument im täglichen Notiz-Speicherpfad des Notizbuchs. Verwende für Tagebuch-/Journal-/Tagesnotizanfragen dailynote create (nicht document create), um die heutige Notiz zu öffnen, und dann dailynote append/prepend, um Inhalte hinzuzufügen.

Notizbuch-Symbol vs. Dokument-Symbol

attr set ändert das Symbol eines Dokumentblocks – es kann NICHT das Symbol eines Notizbuchs setzen. Verwende für Notizbücher notebook set-icon (bestimmtes Emoji) oder notebook random-icon (zufälliges Emoji).

Globale Flags

Diese Flags sind für jeden Unterbefehl verfügbar:

Flag	Beschreibung
-w, --workspace <pfad>	Arbeitsbereichspfad (erforderlich für alle Befehle außer workspace; optional für serve, das standardmäßig den Standard-Arbeitsbereich verwendet).
-f, --format <table|json>	Ausgabeformat (Standard: table)
-v, --log-level <zeichenkette>	Protokollierungsstufe: off, trace, debug, info, warn, error, fatal (Standardwert ist system.logLevel in conf.json)
--dry-run	Validiert und zeigt an, was passieren würde, ohne Änderungen vorzunehmen
--home-dir <pfad>	Basisverzeichnis für die Benutzerkonfiguration (Standard ist das System-Benutzerverzeichnis)

Hinweis: Alle Flags außer -w (oder --workspace) sind optional. Die CLI verwendet Standardwerte, wenn optionale Flags nicht angegeben werden.

Unterbefehl-Referenz

Detaillierte Flags und Beispiele für jeden Befehl findest du in references/commands.md.

Befehl	Unterbefehle
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 "<anweisung>"	(direkt)
siyuan search <abfrage>	(direkt, mit 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	(direkt, mit Flags)
siyuan completion	bash, fish, powershell, zsh

Hinweis: serve akzeptiert alle globalen Flags plus eigene Flags (--accessAuthCode, --attach-ui, --enable-pprof, --lang, --mode, --port, --readonly, --ssl, --safe-mode, --wd). Es erfordert kein -w; die vollständige Flag-Liste findest du in references/commands.md.