Carrot404/siyuan-skill

Skill CLI de SiYuan Note

Descripción general

SiYuan Note proporciona una CLI (siyuan) para gestionar espacios de trabajo, libretas, documentos, bloques y más. El binario debe estar disponible en PATH (verifica con siyuan --version).

Versión de la CLI: v3.8.9. Los comandos mostrados a continuación reflejan esta versión.

Nota: Si siyuan no se encuentra en PATH, prueba con SiYuan-Kernel como nombre de comando alternativo.

Flujo de trabajo

Sigue esta secuencia para cada solicitud del usuario:

1. Descubrir espacios de trabajo disponibles

Ejecuta siyuan workspace list (no se necesita la bandera -w) para obtener la lista de espacios de trabajo registrados. Si el usuario no ha especificado un espacio de trabajo, preséntale la lista y pídele que elija.

siyuan workspace list
siyuan workspace info          # muestra el espacio de trabajo predeterminado actual

2. Fijar la ruta del espacio de trabajo

Una vez que el usuario selecciona un espacio de trabajo (o proporciona una ruta directamente), almacena la ruta del espacio de trabajo y úsala como argumento -w para todos los comandos posteriores (excepto los subcomandos de workspace).

3. Ejecutar el comando solicitado

Construye y ejecuta el comando objetivo con -w <ruta-del-espacio-de-trabajo> (excepto el subcomando workspace). Usa -f json para obtener salida programática al analizar resultados.

Si un comando falla, verifica: (1) la ruta del espacio de trabajo es válida, (2) se proporcionan las banderas necesarias como --id, (3) el subcomando existe en la versión instalada de la CLI.

Patrones comunes

Obtener IDs de bloques/documentos

Muchos comandos requieren un ID de bloque o documento (--id). Obtén los IDs mediante:

• siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <ruta> -f json — lista IDs de documentos
• siyuan document list --notebook <id> -w <ruta> -f json — lista documentos en una libreta
• siyuan search <palabra-clave> -w <ruta> -f json — busca y obtén IDs de los resultados

Operaciones destructivas: verificar, previsualizar, confirmar

Trata las operaciones de eliminación/limpieza (remove, delete, clean, clear, purge), reversión (history rollback, repo checkout, repo file rollback) y reemplazo/sobrescritura (por ejemplo, import data, sobrescribir un archivo existente con file write, o comandos de plantilla con --overwrite) como operaciones destructivas.

1. Verifica el espacio de trabajo, los IDs/rutas objetivo y el alcance afectado usando comandos de solo lectura. Comprueba si también se verán afectados documentos hijos, datos relacionados o contenido existente; no infieras el alcance solo por el nombre del comando.
2. Ejecuta el comando previsto con --dry-run primero e inspecciona su salida:

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

   Una ejecución en seco exitosa no es aprobación del usuario ni prueba de que todos los datos afectados fueron listados. Si solo valida argumentos o muestra una vista previa genérica, usa una inspección de solo lectura para establecer el alcance. Si la ejecución en seco falla o no se pueden establecer los efectos, detente y explica la limitación; no reintentes sin --dry-run para omitirlo.
3. Si la autorización del usuario o el alcance afectado no están claros, o la vista previa revela efectos más allá de la solicitud, resume el espacio de trabajo, los objetivos y las consecuencias y pide confirmación explícita antes de proceder. No adivines objetivos ni expandas silenciosamente el alcance.
4. Una vez que el alcance esté verificado y autorizado, crea una instantánea de recuperación en el espacio de trabajo objetivo antes de ejecutar la operación destructiva:

   siyuan repo create --memo "Antes de <breve descripción de la operación destructiva>" -w <ruta>
   

   Verifica que la creación de la instantánea haya sido exitosa. Si falla, detente e informa del error; no continúes con la operación destructiva. Una instantánea al final de la sesión del estado modificado no reemplaza este punto de recuperación previo a la operación.
5. Ejecuta sin --dry-run solo cuando los efectos verificados coincidan con la solicitud del usuario o la confirmación explícita, manteniendo el mismo espacio de trabajo, objetivos y opciones. Si alguno de estos cambia, repite la verificación, la vista previa y la instantánea previa a la operación.

Análisis de salida JSON

Usa -f json para análisis programático. La estructura JSON depende del subcomando: workspace list devuelve un array, mientras que workspace info devuelve un objeto. Inspecciona la estructura de salida del comando antes de filtrar con jq o herramientas similares; no asumas que cada resultado es un array.

Errores de bloqueo de espacio de trabajo

Si un comando sale con el código 24 e informa lock workspace [...] failed, el espacio de trabajo ya está en uso por otro proceso de SiYuan (por ejemplo, la aplicación de escritorio). Cierra el otro proceso o usa un espacio de trabajo diferente.

Instantánea después de operaciones de escritura

Realiza un seguimiento de los cambios de datos reales por separado para cada espacio de trabajo durante la conversación, incluyendo cambios parciales dejados por comandos fallidos. La creación de una instantánea en sí misma no cuenta como un nuevo cambio de datos que requiera otra instantánea.

Antes de finalizar la tarea o terminar la sesión, resume los cambios y crea una instantánea de datos en cada espacio de trabajo modificado, usando la ruta de ese espacio de trabajo y su propio resumen de cambios:

siyuan repo create --memo "<breve resumen de los cambios en este espacio de trabajo>" -w <ruta-del-espacio-de-trabajo-modificado>

El --memo debe describir de manera concisa lo que se creó/modificó/eliminó (por ejemplo, "Creados 3 docs en /Proyectos, actualizado README, eliminadas notas obsoletas"). Verifica el éxito para cada espacio de trabajo; si una instantánea falla, informa del espacio de trabajo afectado y del error en lugar de afirmar que se guardó. Omite espacios de trabajo sin cambios de datos; una sesión de solo lectura no requiere instantáneas.

Estas instantáneas preservan el estado posterior a los cambios. No reemplazan las instantáneas de recuperación previas a la operación requeridas para operaciones destructivas.

Conceptos del dominio

Comprender estos conceptos específicos de SiYuan es esencial para un uso correcto de la CLI:

Bloque: la unidad fundamental

Todo es un bloque con un ID único. Un documento es un bloque de documento (tipo d, es decir, NodeDocument) que sirve como raíz; los bloques de contenido (encabezados, párrafos, listas, código, tablas) forman un árbol debajo de él.

Bloques contenedores (pueden contener bloques hijos, válidos como --parent): documento, blockquote, lista, elemento-de-lista, super-bloque, callout, pestañas, elemento-de-pestaña. Bloques hoja (no pueden contener hijos, inválidos como --parent): encabezado, párrafo, bloque-de-código, bloque-matemático, tabla, bloque-HTML, salto-temático, video, audio, widget, iframe, vista-de-atributo, incrustación-de-consulta-de-bloque.

pestañas/elemento-de-pestaña son los tipos de bloque introducidos para contenedores con pestañas; aparecen en la lista de filtros de tipo search -t como tabs y tabItem.

Jerarquía de encabezados: usa --previous, no --parent

Los encabezados (h1-h6) son bloques hoja. Los bloques que aparecen "debajo" de un encabezado en la interfaz son sus hermanos siguientes en el AST, no sus hijos. Para insertar un bloque debajo de un encabezado, pasa el ID del encabezado (o el ID del último bloque actualmente debajo de él) como --previous, no como --parent:

siyuan block insert --parent <idDoc> --previous <idEncabezado> --data "texto" -w <ruta>

Listas anidadas: elemento-de-lista no puede contener directamente otro elemento-de-lista

Un elemento-de-lista no puede contener directamente otro elemento-de-lista. Para anidar listas, crea una lista (NodeList) como hija del elemento-de-lista externo, luego agrega elementos-de-lista a esa lista interna. El padre de un elemento-de-lista siempre debe ser una lista.

hPath: ruta legible para humanos

Un hPath es la ruta basada en el título que se muestra en el árbol de documentos (por ejemplo, /Diario/2024/Junio). Renombrar un documento cambia su hPath pero no su ID.

• document list y document move: --hpath acepta una ruta basada en el título; --path acepta una ruta interna basada en ID (predeterminado: /). Estas banderas no son intercambiables.
• document create: --path especifica la ruta del documento padre (predeterminado: /); este comando no proporciona --hpath. Consulta siyuan document create --help para la versión instalada en lugar de asumir que comparte las banderas de ruta de list/move.

block update: reemplazar, no añadir

block update reemplaza TODO el contenido de UN bloque con nuevo markdown. NO crea ni añade nuevos bloques. Para modificar contenido existente y agregar contenido nuevo, llama primero a block update, luego a block append/prepend/insert como llamadas separadas. Pasa --lock-type para rechazar la actualización cuando el tipo de bloque analizado del nuevo contenido difiere del tipo de bloque existente.

document move vs block move

document move reubica un documento completo (y todos sus hijos) a la libreta y ruta padre de destino, usando --hpath para una ruta basada en título o --path para una ruta interna. block move reposiciona un solo bloque de contenido bajo un nuevo bloque padre.

Nota diaria: cuándo usar dailynote vs document

Una nota diaria es un documento especial en la ruta de guardado de notas diarias de la libreta. Para solicitudes de diario/bitácora/nota diaria, usa dailynote create (no document create) para abrir la nota de hoy, luego dailynote append/prepend para agregar contenido.

Icono de libreta vs icono de documento

attr set cambia el icono de un bloque de documento — no puede establecer el icono de una libreta. Para libretas usa notebook set-icon (emoji específico) o notebook random-icon (emoji aleatorio).

Banderas globales

Estas banderas están disponibles en cada subcomando:

Bandera	Descripción
-w, --workspace <ruta>	Ruta del espacio de trabajo (requerida para todos los comandos excepto workspace; opcional para serve, que usa el espacio de trabajo predeterminado)
-f, --format <table|json>	Formato de salida (predeterminado: table)
-v, --log-level <cadena>	Nivel de registro: off, trace, debug, info, warn, error, fatal (predeterminado: conf.json system.logLevel)
--dry-run	Valida y muestra lo que sucedería sin hacer cambios
--home-dir <ruta>	Directorio base para la configuración del usuario (predeterminado: el directorio base del usuario del sistema)

Nota: Todas las banderas excepto -w (o --workspace) son opcionales. La CLI usará valores predeterminados si no se especifican banderas opcionales.

Referencia de subcomandos

Para banderas detalladas y ejemplos de cada comando, carga 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>"	(directo)
siyuan search <consulta>	(directo, con banderas)
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	(directo, con banderas)
siyuan completion	bash, fish, powershell, zsh

Nota: serve acepta todas las banderas globales más sus propias banderas (--accessAuthCode, --attach-ui, --enable-pprof, --lang, --mode, --port, --readonly, --ssl, --safe-mode, --wd). No requiere -w; consulta references/commands.md para la lista completa de banderas.