Bases de conocimientos locales

Una base de conocimientos local es una carpeta normal de archivos Markdown que usted escribe y organiza en VelaTerm. Las notas y los archivos adjuntos permanecen en esa carpeta, por lo que puede seguir editándolos con otros editores. Algunos elementos de menú llaman «cuaderno» a una base de conocimientos local; ambas palabras designan la misma carpeta.

La «Base de conocimientos de sesiones» integrada se encuentra junto a sus bases de conocimientos locales. Contiene el conocimiento que los agentes organizan a partir de sus sesiones y mantiene sus propios artículos, fuentes e historial de revisiones; consulte Base de conocimientos de sesiones.

Apertura de la base de conocimientos

Haga clic en el icono de conocimiento del panel derecho (su información sobre herramientas es «Base de conocimientos»). En el centro se abre una pestaña «Base de conocimientos» con la página de inicio:

un cuadro de búsqueda («Busca en el conocimiento de las sesiones y en las notas locales…»; consulte la sección Búsqueda más abajo);
la «Base de conocimientos de sesiones»;
sus «Bases de conocimientos locales»;
los botones «Abrir base de conocimientos» y «Crear base de conocimientos».

El panel derecho muestra un árbol con tres raíces: «Base de conocimientos de sesiones», «Sesiones archivadas» y «Bases de conocimientos locales». Haga clic en una flecha para expandir una carpeta en el propio árbol; se pueden expandir varias bases de conocimientos a la vez. Haga clic en el nombre de una carpeta para mostrar su contenido y en una nota para abrirla. El enlace «Bases de conocimientos» de la parte superior del árbol vuelve a la página de inicio, y el botón «Subir un nivel» del encabezado de una página lleva a la página superior sin salir de la base de conocimientos.

Las notas se abren en pestañas de documento normales, con las mismas funciones de edición, guardado, búsqueda y exportación a PDF que cualquier otro archivo Markdown (consulte Pestañas de documentos y navegador). La pestaña «Base de conocimientos» permanece en la barra de pestañas para que pueda volver al punto en el que estaba.

Apertura o creación de una base de conocimientos local

Abrir: haga clic en «Abrir base de conocimientos» y elija una carpeta. La aplicación de escritorio muestra el selector de carpetas del sistema; un cliente de navegador muestra un explorador de carpetas del ordenador conectado. Una bóveda de Obsidian existente se puede abrir directamente: los archivos permanecen donde están, y las carpetas ocultas, como .obsidian, no se indexan ni se modifican.
Crear: haga clic en «Crear base de conocimientos», introduzca un «Nombre», elija una «Carpeta» (o use «Examinar»; la ubicación sugerida es ~/Notes) y confirme. VelaTerm crea la carpeta y la abre. La carpeta superior debe existir y no debe haber ya una carpeta con el mismo nombre; de lo contrario, VelaTerm muestra «El destino ya existe. Elige otro nombre o carpeta». Para usar una carpeta existente, elija «Abrir base de conocimientos».
Renombrar: haga clic con el botón derecho en una base de conocimientos del árbol y elija «Renombrar». Esta acción cambia el nombre de la carpeta en el disco.
Cerrar: haga clic en «Cerrar cuaderno» en la barra de herramientas de la base de conocimientos, o haga clic con el botón derecho en ella en el árbol. Al cerrarla, la carpeta se quita de la lista; sus archivos permanecen en el disco. Si vuelve a abrir la misma carpeta, su papelera y su historial de importaciones siguen disponibles.

«Local» se refiere al ordenador en el que se ejecuta el servidor de VelaTerm al que está conectado. En un cliente de navegador, «Abrir base de conocimientos» explora las carpetas de ese ordenador, y al importar se suben a ese ordenador los archivos que elija en el navegador.

Importación de archivos y carpetas

Abra la base de conocimientos de destino y haga clic en «Importar» en su barra de herramientas.
Elija la «Carpeta» de destino y, a continuación, «Elegir archivos» o «Elegir carpeta», o bien arrastre archivos y carpetas al área de importación.
Revise la lista y confirme.

La importación se ejecuta en segundo plano, de modo que puede cambiar de página o abrir notas mientras se copian los archivos. Su progreso aparece en la barra de herramientas de la base de conocimientos y en la página de inicio, y se puede cancelar desde el cuadro de diálogo de importación o desde «Historial de importaciones». Al terminar, un aviso muestra el número de archivos importados y omitidos; si la ventana no está activa, aparece una notificación del sistema («Importación finalizada» o «Error en la importación»). En cada base de conocimientos solo puede haber una importación en curso a la vez.

Una importación copia los archivos tal cual, incluidos los nombres de archivo con caracteres no ASCII, la estructura relativa de carpetas y los archivos adjuntos, y nunca modifica los originales. Al importar una carpeta se incluye la propia carpeta. Si algún archivo fuera a sobrescribir otro existente, se rechaza todo el lote. Los archivos ocultos y las carpetas de configuración ocultas se omiten. Los selectores de archivos del navegador no proporcionan las carpetas vacías, por lo que estas no se importan.

Una importación puede contener hasta 5000 archivos (los archivos ocultos omitidos cuentan para este límite) y hasta 1 GiB en total, con un máximo de 100 MiB por archivo. Los archivos se preparan primero en una ubicación provisional y solo aparecen en el destino cuando ha llegado el lote completo, de modo que una carga interrumpida nunca aparece como una nota a medio escribir.

«Historial de importaciones» enumera cada importación con su hora, el destino («Raíz de la base de conocimientos» para la carpeta superior), el estado («Importando», «Completada», «Fallida», «Cancelada» o «Interrumpida»), el número de archivos importados y omitidos, el tamaño y la duración. Haga clic en «Archivos (N)» para ver cada archivo y el motivo por el que se omitió. «Eliminar registro» quita la entrada del historial; los archivos importados no se eliminan. Una importación cuyo progreso lleva más de dos minutos detenido, por ejemplo porque la aplicación se cerró de forma inesperada, se marca como «Interrumpida»; al eliminar su registro también se eliminan los archivos que se habían preparado para ella.

Redacción y organización de notas

La página de una base de conocimientos tiene las vistas «Notas recientes», «Papelera» e «Historial de importaciones», un botón «Nueva nota» y, en la barra de herramientas, los botones «Nueva carpeta», «Importar» y «Cerrar cuaderno». La lista de notas se puede filtrar por etiqueta («Todas las etiquetas») y ordenar por «Actualización reciente» o «Título».

Mientras se muestra la página de una base de conocimientos, ⌘N / Ctrl+N crea una «Nueva nota», ⌘O / Ctrl+O abre «Apertura rápida» (para buscar una nota por su ruta) y ⌘⇧F / Ctrl+Shift+F lleva al cuadro «Buscar notas…».
Para renombrar una nota, haga clic con el botón derecho en ella en el árbol y elija «Renombrar». Para moverla, arrástrela a otra carpeta de la misma base de conocimientos. «Eliminar» la envía a la papelera de la base de conocimientos.
Con una carpeta abierta, «Renombrar o mover» traslada la carpeta a una ruta relativa a la raíz de la base de conocimientos; la carpeta superior ya debe existir. Cuando se mueve una nota o una carpeta, se actualizan los enlaces de las demás notas de la misma base de conocimientos; el texto de los enlaces se conserva y el código no se modifica.
Los elementos eliminados van a una carpeta .vkb-trash dentro de la base de conocimientos. Abra «Papelera» y haga clic en «Restaurar» para recuperar un elemento; nunca se sobrescribe un archivo existente con el mismo nombre.
Las etiquetas proceden de #tag en el texto y de la clave YAML tags, escrita como lista o como matriz.
Las imágenes pegadas en una nota se guardan en una carpeta assets junto a la nota.

El árbol y las listas se actualizan aproximadamente cada cinco segundos mientras la página está visible, y también cuando la ventana vuelve a estar activa. Una pestaña de documento abierta detecta los cambios realizados por otros programas y ofrece volver a cargar el archivo.

Las páginas de la base de conocimientos, los cuadros de diálogo, el historial de importaciones, las búsquedas, el alcance de la búsqueda, las etiquetas, la ordenación y la apertura rápida tienen sus propias URL, de modo que puede actualizar la página o usar los botones Atrás y Adelante del navegador. El texto sin guardar y los datos introducidos en los formularios no forman parte de la URL.

Búsqueda

Página de inicio: busca a la vez en la base de conocimientos de sesiones y en todas las bases de conocimientos locales, y agrupa los resultados por origen. Las sesiones archivadas no se incluyen.
Panel derecho: «Buscar notas…», encima del árbol, busca en todas las bases de conocimientos locales.
Página de una base de conocimientos: «Buscar notas…» busca en los nombres, las rutas y el texto de las notas. «Alcance de la búsqueda» alterna entre «Esta base de conocimientos» y «Todas las bases de conocimientos».

Si escribe varias palabras, deben coincidir todas. Cada resultado muestra su base de conocimientos o su grupo de sesión, un fragmento, el número de línea, el número de coincidencias y las «Notas relacionadas» a las que enlaza la nota; haga clic en cualquiera de ellos para abrirlo. Use ↑ y ↓ para seleccionar un resultado, Enter para abrirlo y Esc para borrar la búsqueda. Los resultados se ordenan primero por las coincidencias en el nombre o la ruta, después por el número de coincidencias y, por último, por la actualización más reciente. Se muestran hasta 100 resultados; cuando hay más, la lista termina con «Solo se muestran los primeros resultados. Ajusta la búsqueda para ver el resto».

VelaTerm busca primero coincidencias exactas y solo recurre a coincidencias aproximadas cuando no encuentra ninguna; en ese caso muestra «No hay coincidencias exactas. Se muestran resultados aproximados». La búsqueda aproximada se aplica a las palabras formadas por letras latinas y dígitos: letras en orden (knwl encuentra knowledge), iniciales (kb encuentra knowledge base) y pequeños errores de escritura (un error en palabras de cuatro o más caracteres y dos en palabras de ocho o más; knoledge encuentra knowledge). El chino y otros textos no latinos solo se buscan por coincidencia exacta.

Enlaces y compatibilidad con archivos existentes

VelaTerm reconoce las formas habituales [[note]], [[folder/note|label]] y [[note#heading]], los enlaces relativos estándar de Markdown y ![[image.png]]. Los usa para actualizar los enlaces cuando se mueven notas, para mostrar las «Notas relacionadas» en los resultados de búsqueda y en los comandos vkb que se describen más abajo. En el editor, los enlaces [[…]] se muestran como texto sin formato. Cuando varios archivos comparten nombre, un enlace corto solo se resuelve si el destino es único; en caso contrario, escriba la ruta de la carpeta.

Los archivos siguen siendo Markdown sin formato especial, y los metadatos YAML iniciales (front matter) permanecen en el archivo; el modo «Código fuente» del editor los muestra tal cual. Los archivos Markdown que no están codificados en UTF-8 o que superan los 5 MiB no aparecen como notas y se cuentan en «Omitidos». Una base de conocimientos puede contener hasta 50 000 archivos y carpetas; una carpeta más grande no se puede abrir y muestra «El archivo o la selección supera los límites del cuaderno». Los enlaces simbólicos no se siguen.

Estas funciones cubren el trabajo diario con archivos locales, carpetas, Markdown, enlaces y búsqueda. No se admiten los complementos, los temas, Canvas, las referencias a bloques, las notas incrustadas ni los alias YAML de Obsidian; los archivos correspondientes se dejan sin cambios. Para conocer el modelo de archivos y la sintaxis de los enlaces, consulte la documentación de Obsidian sobre bóvedas, enlaces internos y archivos adjuntos.

Copia desde la base de conocimientos de sesiones y consultas de agentes

Abra un artículo de la base de conocimientos de sesiones, elija «Copiar a un cuaderno local» y, a continuación, seleccione la base de conocimientos de destino y el nombre del archivo. La copia es una nota Markdown independiente; el artículo original, sus instantáneas de origen y su historial de revisiones permanecen donde están.

En una sesión de VelaTerm, usted o un agente pueden leer con vkb las bases de conocimientos locales registradas:

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes busca en todas las bases de conocimientos locales registradas en el servidor actual. Cada resultado incluye vaultId, vaultName, path, absolutePath, line, matches, score, matched (el texto que coincidió realmente), related (las notas a las que enlaza esta nota) y summary (el texto que rodea la coincidencia). La respuesta también indica total, hasMore, unavailable (las bases de conocimientos que no se pudieron leer) y fuzzy (si los resultados son aproximados). Se devuelven hasta 100 resultados.
note devuelve el texto de una nota, su esquema, sus enlaces, sus enlaces entrantes y sus etiquetas.
search devuelve coincidencias de la base de conocimientos de sesiones, de las notas locales y, cuando existe un índice de código, del grafo de código (consulte Grafo de código y base de conocimientos).

Estos comandos son de solo lectura. Nunca modifican las notas, y VelaTerm no añade automáticamente el contenido de las bases de conocimientos a las sesiones.

Almacenamiento y registros

Los archivos del disco son la copia de referencia de sus notas y archivos adjuntos. La base de datos de la aplicación (tablas kb_*) solo almacena la lista de bases de conocimientos registradas, los registros de la papelera, el historial de importaciones y una caché de búsqueda que se puede reconstruir. La base de conocimientos de sesiones usa sus propias tablas memory_*.

Las operaciones de apertura, escritura, traslado, eliminación, restauración e importación quedan anotadas en el registro de ejecución con un ID de operación, recuentos y el tiempo empleado, nunca con el contenido de las notas. Estas líneas usan el evento knowledge; cuando VLX_LOG_DIR no está definida, VLX_KNOWLEDGE_LOG_DIR establece su directorio. El historial de importaciones se almacena en la base de datos y se muestra en la página «Historial de importaciones». Para hacer una copia de seguridad completa de una base de conocimientos, conserve tanto su carpeta como los datos de la aplicación, que contienen su papelera y sus registros de importación.